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Chapter  1 


Introduction 


1.1.  Background 

The  Geographic  Resources  Analysis  Si^jport  System  (GRASS)  is  a  geographic 
information  system  (GIS)  designed  and  developed  by  researchers  at  the  U.S.  Army 
Construction  Engineering  Research  Laboratory  (USACERL).  GRASS  provides 
software  capabilities  suitable  for  otganizing,  portrayipg  and  analyzii^  digital  spatial 
dnfa 

Stiice  the  first  release  of  GRASS  software  in  1985,  the  number  of  users  and 
applications  has  r^idly  grown.  Because  GRASS  is  distributed  with  source  code,  user 
sites  (including  many  government  orgardzations,  educational  institutions,  and  private 
firms)  are  able  to  customize  and  enhance  GRASS  to  meet  their  own  requirements. 
While  researchers  at  USACERL  still  maintain  and  sipport  GRASS,  and  still  develop 
and  organize  new  versions  of  GRASS  for  release,  progiammeis  at  lunnerous  sites  now 
work  directly  with  GRASS  source  code. 


1.2.  Objective 

Those  who  work  with  GRASS  source  code  need  detailed  information  on  the  structure 
and  organization  of  the  software,  and  on  procedures  and  standards  for  programming 
and  documentation  The  objective  of  this  manual  is  to  provide  the  necessary 
information  for  programmers  to  understand  and  enhance  GRASS  software. 


1.3.  Ai^roach 

GRASS  software  is  continuously  ipdated  and  improved.  Software  enhancements  are 
developed  at  various  sites,  and  submitted  to  USACERL  to  be  shared  with  other  sites 
and  included  in  future  releases  of  GRASS.  Improvements  to  the  code  are  periodically 
incorporated  into  new  releases  (which  occur  approxiroately  once  per  year). 

With  each  new  release  of  GRASS,  more  and  more  sites  have  begun  working  directly 
with  GRASS  source  code.  Sites  are  encouraged  to  iLse  standard  procedures  in 
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development  of  new  GRASS  capabilities.  Sites  that  develop  GRASS  software  ate 
encouraged  to  learn  and  use  GRASS  programming  libraries,  and  to  use  standard 
procedures  for  coding,  commenting  and  documoiting  software.  Ihe  use  of  GRASS 
libraries  and  coiwentions  will: 

(1)  Eliminate  diq;>lication  of  functions  that  already  east  in  GRASS 
libraries; 

(2)  Increase  the  capability  of  multiple  sites  to  share  enhancements; 

(3)  Reduce  problems  in  adaptmg  contributed  GRASS  capabilities  to  new 
data  structures  and  new  versions  of  GRASS  software; 

(4)  Rovide  some  common  elements  (such  as  documentation  and  user 
interfaces)  for  users  who  use  code  contributed  from  multiple  sites, 
and  reduce  the  learning  curve  associated  with  each  contributed 
curability. 

The  first  GRASS  Ftogrammer's  Manual  was  developed  for  GRASS  2.0  (released  by 
USACERL  in  1987).  However,  there  were  numerous  and  fundamental  changes  made 
in  GRASS  3.0  (released  in  1988).  Ratiier  than  revise  the  eyistiT^  FVogrammer's 
Manual,  USACERL  researchers  elected  to  draft  a  new  and  more  complete  GRASS 
Rogrammei's  Reference  Manual  for  GRASS  3,0.  The  approach  used  in  the 
development  of  tins  manual  irrsrolves  a  systematic  effort  to  describe  GRASS 
development  guidelines,  user  interfaces,  data  structures,  programming  libraries  and 
peripheral  drivers. 


1.4  Scope 

Information  in  (his  manual  is  valid  for  GRASS  version  3.0,  released  in  November, 
1988.  As  changes  are  made  to  GRASS  libraries,  data  structures,  and  user  interfaces, 
elements  in  tins  manual  will  require  updating.  Bans  to  perform  updates,  and  the 
availabilify  of  these  updates,  will  be  armouraed  in  the  newsletter  GRASSClippings  and 
other  GRASS  information  forums. 


1.5.  Mode  of  Tedmology  Transfer 

Army  and  Corps  of  Eiigineer  organizations  can  aquire  GRASS  software  from 
USACERL.  Several  other  federal  organizations  provide  di^iibution  and  support 
services  for  GRASS  within  their  own  agencies,  and  several  educational  institutions  and 
private  firms  also  provide  distribution,  training  and  support  services  for  GRASS. 
Current  information  on  the  status  and  availability  of  sovices  for  GRASS  can  be 
obtained  from  the  GRASS  Information  Center.^ 


'  See  ^1.6  GRASS  Infoirmtion  CeiUer  \p.  4\  for  phone  nurrbeis  and  mail  addresses. 
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This  manual  should  prove  to  be  a  valuable  resource  facilitating  GRASS  software 
development  efforts  at  die  numerous  government  agency,  educational  institutions  and 
private  firms  that  now  use  GRASS  and  plan  to  modify,  enhance  or  customize  the 
software.  Sites  that  develop  new  analytical  capabilities  or  peiipheial  drivers  for 
GRASS  are  encouraged  to  share  their  products  with  others  in  the  GRASS^GIS  user 
community.  To  facilitate  this  sharing  process  among  usa*,  siqipoit  and  development 
sites,  several  forums  have  been  established  Ihese  include  the  following: 

The  GRASS  Information  Center, 

The  GRASS  Inter-Agency  Steering  Committee, 

An  annual  GRASS'GIS  User  Group  Meeting, 

,  GRASSClippings ,  a  quarterly  newsletter,  and 
GRASSNET,  an  electronic  mail  and  software  retrieval  forum. 

The  GRASS  Information  Center  maintains:  (1)  a  set  of  publications  on  GRASS  arri 
GRASS-related  items,  (2)  updated  information  on  locations  that  distribute  and  support 
GRASS  software  and  on  training  courses  for  GRASS,  (3)  die  mailing  list  for  the 
newsletter  GBASSClippings ,  and  (4)  updated  information  on  the  status  of  GRASS  user 
group  meetings  and  software  releases. 

The  GRASS  Inter-Ageny  Steaing  Committee  is  an  informal  organization  with 
members  from  government  agencies  and  other  organizations  that  use,  sipport  and 
enhance  GRASS.  This  organization  ponsors  the  annual  User  Group  Meeting  and  the 
quarterly  newsletter.  It  holds  at  least  two  meetings  annuially  to  share  and  coordinate 
GRASS  plans  amorig  the  participating  agencies. 

The  annual  GRASS^GIS  User  Gratp  Meeting  is  hosted  each  year  by  one  of  the 
member  agencies  of  the  Steering  Committee.  Ftpers,  demonstrations,  and  discussion 
panels  present  GRASS  applications  and  software  development  issues.  The  meeting 
provides  opportunities  for  current  and  potential  users  to  share  and  demonstrate  new 
GRASS  sofWare. 

The  GRASSClippings  newsletter  is  published,  approximately  four  times  a  year,  to 
provide  information  to  artyone  interested  in  GRASS  software.  The  newdetter  includes 
articles  on  software  development,  hardware  options  and  applications  of  GRASS. 

GRASSNETT  is  an  electronic  mail  forum  that  provides  a  mechanism  through  which 
GRASS  user  and  development  sites  can  exchange  messages.  It  can  be  reached  via 
Arpanet,  Internet  and  other  networks.  GRASSNET  also  includes  a  library  of 
contributed  software  available  for  usei^  to  retrieve  and  review.  Thus,  new  software  is 
available  before  it  is  integrated  into  a  formal  release  of  GRASS  code. 
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1.6.  GRASS  Informalkxi  Center 

Sites  wishing  to  contribute  code  to  GRASS,  or  wanting  to  participate  in  ariy  of  ttese 
GRASS/GIS  user  communily  foiunos,  should  contact  the  GRASS  Infomsition  Center 
by  phone  at:  (800)-USA-CERL,  ejctension  220  or  (217)-373-7220;  by  U.&  nail  at: 
GRASS  Information  Center,  USACERL,  RO.  Box  4006,  Qampaign,  IL,  61ffl4r4005; 
or  by  electronic  mail  at:  giass@ceri.cecer.army.nril. 
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Ch^pter2 

Devdopment  GuMdinps 


GRASS  continues  its  development  with  several  key  objectives  as  a  guide.  TTie 
programmer  should  be  aware  of  these  and  strive  to  write  code  that  blends  well  witti 
existing  capabilities.  All  objectives  are  based  on  an  understanding  of  the  needs  of  the 
end-users  of  GRASS. 


2.1.  Intended  GRASS  Audienoe 

GRASS  is  a  general  putxx)se  geographic  information  system.  Its  intended  users  are 
regional  land  planners,  ecologists,  geologists,  geographers,  archeologists,  and  landscape 
architects.  Used  to  evaluate  broad  land  vse  suitability,  it  is  ideal  for  siting  large 
projects,  managing  paries,  forest,  and  range  land,  and  evaluating  impacts  over  wide 
areas.  These  users  are  generally  NOT  equipped  to  write  programs  or  design  a  system. 
In  many  cases  they  have  never  used  a  computer  or  even  a  keyboard. 

REGIONAL  PLANNING  TOOL  - 

GRASS  is  designed  for  planning  at  the  county,  parit,  forest,  or  range  level.  It  is 
suitable  for  planning  at  a  macro  scale  whqre  the  land  uses  are  larger  than  30 
meters  (or  so,  depending  on  the  database  resolution).  As  yet,  rro.  GRASS  tools 
exist  for  tire  modeliig  and  simulation  of  traffic,  electrical,  water,  and  sewage 
infrastructure  loads,  or  for  the  precise  positioning  of  urban  structures. 

UTM-REFERENCED  - 

To  facilitate  area  calculations,  a  planimethc  projection  was  deared  for  initial 
GRASS  development  PXmding  was  provided  throu^  Army  military  installations 
which  were  familiar  with  the  Universal  Transverse  Mercator  (UTM)  projection 
Due  to  these  factors,  GRASS  developed  around  the  UTM  coordinate  ^stem^ 

INTERAtTlWE- 

GRASS  has  a  strong  interactive  component  Its  multi-level  design  allows  users  to 
work  either  at  a  very  user-friendly  level,  at  a  more  flexible  command  level,  or  at 

^  Tlie  UTM  projection  allows  GRASS  to  assume  equd  area  cells  anywhere  in  the  datshaee. 

It  also  makes  distance  calculations  ample  and  stredghtforward.  'lYiis  will  change  as  future 
releases  allow  other  cooirlinaie  systems  (e.g.,  longitude/Iatitude).  The  changes  will  fsobably 
not  affect  overiay  operations,  but  will  most  likely  change  the  methodology  for  distance  and 
area  calculations. 
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a  programmiiig  level. 

GRAMaORIENrEI)  - 

Many  of  tile  functione  can  be  acconpanied  by  grapUc  output  results. 

FOR  NON-PROGRAMMER  - 

Users  of  GRASS  are  often  first-time  users  of  a  conputer.  To  this  end,  it  is 
important  that  the  programmer  take  the  eictra  time  to  provide  on-line  help,  clear 
prompts,  and  user  tutorials. 

INEXPENSIVE- 

GRASS  can  run  on  microcoirputErs  in  the  under-$10,000  rapge.  Hgter-cost 
equipment  should  be  necessary  only  for  providing  faster  analyses,  ani  nxire  disk 
and  memory  pace. 

PORTABLE - 

This  system  is  intended  to  be  as  portable  as  possible.  At  the  November  1986 
User  Groip  meeting,  grotps  interested  in  GRASS  resoundiii^y  stated  ttet 
portability  was  the  number  one  concern,  ranking  firmly  above  speed  and  user- 
friendliness.  GRASS  code  must  be  compilable  on  a  wide  variety  of  hardware 
configurations. 


l^Q^raimimg  Standards 

FVogramming  is  done  within  the  following  guidelines. 

UNDC-ORIEISrrED  - 

Rimarily  for  the  purpose  of  portability,  GRASS  will  continue  its  development 
under  the  UNIX  operating  system  environment  Rogrammers  should 
accommodate  both  AT&T  (System  5)  and  Berkeley  (UCB  4.2)  UNIX. 

C  LANGUAGE  - 

All  code  is  written  in  the  C  programming  language.  Some  Fbrtran  77  code  has 
occasionally  been  adopted  into  the  sy^em,  but  problems  with  portability, 
efficiency,  and  legibility  hav^e  resulted  in  most  Fortran  programs  being  rewritten 
inC. 

FUNCTION  LEVELS  - 

GRASS  is  designed  witiiin  a  functional  level  scheme.  Each  level  is  designed  to 
perform  particular  functions.  Rogramming  must  be  done  within  this  scheme. 
Briefly,  these  levels  are  as  follows: 

Rill  Interactive  Level  - 

The  new  and  occasional  user  works  at  this  level.  As  of  the  first  writing  of 
this  document,  only  one  program,  the  GRASS  menu,  exists  at  this  level.  It 
is  expected  tiiat  pecialized  models,  natural  language  interfaces,  graphic 
popip  menu  front-ends,  and  fancier  menus  will  be  developed  in  the  fuhire. 
Programs  developed  at  tins  level  may  be  pecifically  designed  for  one 
hardware  arrangement 

Command  Interactive  Level  - 

This  is  the  level  most  used.  Using  the  user' s  login  shell,  GRASS  commands 
are  made  avail^le  through  modification  of  the  PATH  variable.  Commands 
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at  dis  level  sere  faigMy  interactive.  Help  and  on-line  maniifll  commands  are 
available.  Hstorically,  these  programs  have  included  both  user  inteiface  and 
program  function  capabilities,  hi  the  future,  more  and  more  commands  at 
this  level  will  actu^y  contain  only  user  inteiface  code;  after  tiie  user  is 
thoroitghly  intmogated,  a  command  line  will  be  constnicted  which  then 
drives  a  program  at  the  Command  Lievel: 

Command  Level  - 

Commands  at  this  level  form  the  G,  D,  P,  etc.  languages.  Ihey  are 
distinguished  by  being  non-intanctive.  All  information  necessaiy  for  the 
execution  of  the  command  is  provided  either  in  the  command  line  or  in  the 
standard  input  stream  (with  no  prompting).  Built  on  top  of  these  commands 
may  be  commands  at  either  of  the  above  two  levels.  The  advanced  user 
who  wants  greater  flexibility  in  the  analysis  options  may  use  these  directiy. 
Further,  the  systmi  analyst  can  use  these  commands  as  a  high-level  GIS 
programming  language  in  concert  with  other  UNIX  utilities. 

Rogramming  Level  - 

For  even  greater  flexibility  in  the  application  of  GRASS,  a  user  has  the 
opportunity  to  progiam  GRASS  functions  in  the  C  language.  The  main 
restrictions  here  are  that  the  programmer  use  the  existing  GRASS  function 
librEDies  to  the  greatest  extent  possible,  and  sipport  both  AT&T  and 
Bericeley  UNIX. 

library  Level  - 

Woilc  at  the  library  level  should  be  done  with  the  cooperation  and  approval 
of  one  groip.  At  this  writirg,  that  groip  is  the  GRA^  programming  staff 
at  USACEEIL.  Those  functions  most  critical  are  those  that  interface  the 
data  It  is  believed  tiiat  these  functions  will  be  more  permanent  than  the 
database.  Though  the  database  may  change,  tiiese  finxtions  (and  the 
programmiig  environment)  will  not 


2^  Documentation  Standart^ 

GRASS  is  a  public  domain  system.  While  such  i^stems  are  usually  inexpensive  to  new 
sites  wishing  to  adopt  them,  costs  incurred  in  putting  up  the  system,  modifying  the 
code,  and  understarxling  the  product  can  be  very  high.  To  minimize  these  costs, 
GRASS  programs  shall  be  thoroughly  documented  at  several  levels. 

Source  code  - 

The  source  code  for  the  furrtions  should  be  liberally  sprinkled  with 
descriptive  variables,  algorithm  explanations,  atxl  function  descriptions. 
On-Une  help  - 

Brief  help/information  will  be  avtelable  for  the  new  user  of  a  program 
On-line  manual  - 

Manual  entries  in  the  style  of  the  UNIX  manual  entries  will  also  be  available 
to  the  user. 
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'Putorial  - 

Ihe  tools  &at  are  loore  involved  or  difficult  to  use  sh^  be  accompanied  by 
tutoiial  documents  v^ch  teach  a  user  how  to  use  the  code.  These  have 
been  written  in  nroff/tzoff  usiiig  the  ms  macro  package.^  Fined  documents 
have  been  kept  separate  from  the  GRASS  duectories,  thou^  it  is  suggested 
that  they  appear  with  appropriate  "makefiles"  under  $GlSBASEytutoiials.^ 


2  Tliis  pack9ge,  invoked  with  the  -ms  option  to  nroff,  is  docunnented  in  section  7  of  the 
UNIX  menual. 

$GISBASE  is  the  directoiy  vdiere  GRASS  is  inetatled.  See  §i0.2  UNIX  Ehuiromrent 
Ip.  .5/1  fordetail& 
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Chapter  3 

MultirLevei 


As  introduced  in  the  previous  section,  the  overall  GRASS  design  incoiporates  several 
levels: 


Full  Interactive  Level 
Command  Interactive  Level 
Command  Level 
Rpgramming  Level 
Library  Level 


Ea:h  level  is  associated  with  a  different  type  of  user  interface. 


3.1.  General  User 

The  general  GRASS  user  is  someone  with  a  skill  in  some  resource  area  (e.g.,  planning, 
biology,  agronomy,  forestry,  etc.)  in  which  GRASS  can  be  used  tn  support  ^ratial 
analysis.  Such  users  have  no  significant  computer  skills,  may  be  afraid  of  keyboards, 
ktx)w  nrthing  of  UNIX,  and  may  struggle  with  the  learning  curve  for  GRASS.  Such 
users  shoidd  select  the  Full  Interactive  Level,  where  they  are  guided  througdi  the 
options  in  a  friendly  way.  Rngrams  written  at  this  level  may  take  mar^  forms  in  the 
future.  The  promise  of  a  natural  language  capability  may  take  form  here.  Current 
success  with  graphic  menu  systems  in  other  applications  will  lead  to  pleasant  graphic 
screens  with  pull-down  menus.  Interfaces  developed  at  this  level  (and  this  level  only) 
may  be  hardware-specific.  GRASS  may  take  the  form  of  a  voice-activated  system 
wiA  fancy  AI  capabilities  on  one  machine,  while  it  is  driven  by  a  pull-down  menu 
system  which  is  also  tightly  interfaced  to  an  RDBMS  on  anodic.  All  versions, 
hrwever,  will  rely  heavily  on  the  consistent  commands  available  at  the  Cornnand 
Levd.  As  of  this  writing  the  menu  version  of  GRASS  is  the  sole  representative  of 
this  interface.  It  is  anticipated  ftiat  specialized  analysis  models  using  little  or  no  user 
input  will  be  developed  shortly,  rtrakirig  use  of  UNIX  shell  scripts  and  Conmtand 
Level  commands.  These  will  be  written  by  ^stem  analysts  and  will  require  no 
knowledge  of  G  {nograirrmirtg.  Lkrtil  inprovemeirts  in  speed  and  cost  of  hardware  and 
flexibility  of  software  are  available,  most  general  users  of  GRASS  interface  the  system 
through  the  Conunnd  Interactive  Level  level. 
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The  ConmKmd  Interactive  Level  requires  some  knowledge  of  UNIX.  Tlie  user  starts 
up  the  GRASS  tools  individually  through  the  UNIX  shell  (commonly  Bourne  or  Csh). 
Once  a  GRASS  tool  is  started,  the  user  enters  a  veiy  friendly  and  interactive 
eiwironn:?n!i  Users  are  not  prompted  through  graphics.  Romptii^  is  restricted  to 
written  int^actioa 


3,2.  GRASS  IVogiraiiitiier 

The  GRASS  programmer,  uai^g  an  array  of  programming  libraries,  writes  interactive 
tools  and  command  line  tools.  Rngrammers  must  keep  in  mind  that  FYdl  Interactive 
Level  tools  will  be: 

a  Written  for  the  occasional  user, 

b.  Verbose  in  their  prompting; 

c.  Have  available  lots  of  help;  and 

d.  (5ive  the  user  few  options. 

The  programmer  also  writes  Command  Levd  tools.  These: 

a  Can  run  in  batch  (background)  mode; 

b.  Take  input  from  the  command  line,  standard  irput,  or  a  file; 

c.  Can  run  from  a  shell;  and 

d.  Operate  with  a  standard  interface. 


GRASS  programmers  should  keep  the  following  design  goals  in  mind: 

a  Consistent  user  interface; 

b.  Consistent  datebase  interface; 

c.  Functional  consistency; 

d.  Installation  consistency;  and 

e.  (Dode  portability. 

As  much  as  possible,  interacting  with  the  user  (e.g.,  prompting  for  database  files,  or 
full  screen  input  prompting)  must  not  vary  in  style  from  program  to  program.  All 
GRASS  programs  must  access  the  datebase  in  a  sterriard  manner.  Rmctional 
mechanisms  (such  as  automatic  windowing  and  masking  of  cell  data)  which  are 
independent  of  the  particular  algorithm  must  be  incorporated  in  most  GRASS 
programs.  Users  must  be  able  to  install  GRASS  (date,  programs,  and  source  code)  in 
a  consistent  manner.  Finally,  GRASS  programs  must  compile  and  run  on  most  (if  not 
all)  versions  of  UNIX.  To  achieve  these  goals,  all  {Mogramming  must  adhere  to  the 
following  guidelines: 

Use  C  language  - 

This  language  is  quite  standard,  ensuring  very  good  portability.  All  of  tire 
GRASS  system  libraries  are  written  in  C.  With  very  few  exceptions,  the  GRASS 
programs  are  also  written  in  C.  While  UNIX  machines  offer  a  Fortran  77, 
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expeiience  has  that  F77  code  is  not  as  portable  or  paredictable  moved 

between  machines.  Existing  Fbitran  code  to  occaaonally  been  adopted,  but 
programmers  often  prefer  to  rewrite  the  code  in  C. 

Use  Bourne  shell  - 

GRASS  also  noakes  use  of  tee  UNIX  command  interpreter  to  implemert  various 
function  scripts,  such  as  menu  fiont^nds  to  a  suite  of  rriated  functions,  or 
application  macros  combining  GRASS  command  level  tools  and  UNIX  utilities. 
Ibrtabilify  requires  teat  these  scripts  be  written  uripg  tee  Bourne  9iell  (A)in/sh) 
and  no  other.  See  ^24  Writing  GRASS  9iell  Scripts  \p.229l 

Do  not  access  data  directly  - 

llie  GRASS  database  is  NOT  guaranteed  to  retain  its  existing  oiganization  and 
structure.  These  have  changed  in  tee  past;  however,  tee  library  function  calls  to 
the  data  have  remained  more  conristent  over  time.  Rans  do  exist  to  significantiy 
change  the  data  organizatioii  While  the  programmer  should  be  aware  of  the  date 
capabilities  and  limitations,  it  should  not  be  necessary  to  open  and  read  date  files 
directly. 

Use  Gmake  - 

GRASS  code  is  compiled  using  the  Gmake  command,  which  is  a  front-end  to  the 
UNIX  make  utility.  Gmake  combines  some  pre-defined  variables  with  a  file 
called  GmakefUe  in  the  source  drrectoiy  to  create  a  proper  makefile,  and  then 
runs  make  to  couple  the  program.  £^h  source  code  directory  must  have  a 
Gmakefile,  written  by  tiie  programmer,  containing  instructions  for  making  the 
binary  execuitEhles,  nxniual  and  help  entries,  and  other  items  from  the  directory’s 
contents.  The  GmakefUe  does  not  couteixi  hard-coded  references  to  programs, 
libraries,  or  directories  outside  the  current  directory.  Variables  defining  these 
items  are  used  instead.  GmakefUes  remain  identical  system  to  system  thus 
providing  consistency  for  system  installation  and  compilation  See  §i2  Corrpiling 
GRASS  Programs  Using  Gmake  \p.55\  for  more  details. 

Use  GRASS  libraries  - 

Use  of  the  existing  GRASS  programming  libraries  speeds  up  programming 
efforts.  While  user  and  date  interface  may  make  tp  a  large  part  of  a  new 
program,  the  programmer,  using  existing  library  functions,  can  concentrate 
primarily  on  the  analysis  algoritiimB  of  the  new  tool.  Such  programs  will 
maintain  a  consistency  in  date  access  and  (more  importantly)  a  degree  of 
consistency  in  tiie  user  interface.  Each  library  has  a  definition  in  Gmake  to  aid  in 
linking  the  library  duriirg  program  compilation  and  loading.  The  libraries  are 
listed  briefly  below. 

GIS  Library.  This  library  contains  all  of  the  routines  necessary  to  read  and 
write  the  GRASS  grid  cell  date  l^ens  and  their  support  files.  A  standardized 
method  to  prompt  the  user  for  map  names  is  available.  The  library  also  provides 
some  gen^  purpose  tools  like  men»iy  allocation,  buffer  zeromg,  string 
analysis,  and  date  seeirching.  Ninety-nine  percent  of  all  GRASS  programs  use 
routines  from  this  library.  See  §22  GIS  Library  !p.63]. 

S^ment  Library.  For  programs  that  need  random  access  to  an  entire  map  layer. 
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the  s^ment  libiary  ptrovides  an  efficient  paging  scheme  for  gnd  cell  mep& 
While  virtual  memoiy  operating  systems  peifoim  paging,  this  Ubraiy  provides 
better  control  and  efficiency  of  paging-  See  §19  Segment  library  (p.  2791. 

Dig  lifaraty.  While  GRASS  is  piimahly  a  gnd  cell  analysis  and  display  system, 
it  also  has  some  vector  capabilities.  The  principal  uses  of  GRASS  vector  files  are 
to  generate  raster  msps  and  to  plot  base  maps  on  top  of  grid  cell  displays. 
However,  it  is  anticipated  that  additional  analyas  and  data  import  capabilities  will 
be  added  to  the  vector  database.  Many  vector  formats  exist  in  the  GES  worid,  but 
GRASS  has  chosen  to  implement  its  own  internal  vector  format  The  format  is  a 
variant  of  arc-node.  The  Dig  Library  provides  access  to  the  GRASS  vector 
database.  See  §13  Dig  Library  [p.  123]. 

Vask  UDbraory.  This  screen-oriented  user  interface  is  widely  used  in  the  GRASS 
programs.  It  provides  the  programmer  with  a  simple  means  for  di^laying  a 
particular  screen  layout  with  defined  fields  where  the  user  is  prompted  for 
answers.  The  user,  using  the  carnage  return  (or  line-feed)  and  ctri-k  keys,  moves 
from  prompt  to  prompt  filling  an  answer  into  each  fidd.  When  the  ESC  (escape) 
key  is  struck,  the  answers  are  provided  to  the  program  for  analysis.  Users  have 
found  this  interface  pleasant  and  consistent  See  §20  Vask  Library  Ip.  187]. 

Graphics  Ufararies,  Giaphics  design  has  been  a  difficult  issue  in  GRASS 
development  To  ensure  portability  and  competitive  bidding,  GRASS  has  been 
designed  with  grEphics  flexibility  in  mind.  This  has  meant  restricting  graphics  to 
a  minimal  set  of  greplncs  primitives,  which  genially  do  not  make  full  use  of  the 
gr^ihics  capabilities  on  all  GRASS  machines.  Two  libraries,  dfeplaB^  and 
rasteriib,  are  involved  in  generating  graphics.  The  rasterlib  contains  the 
primitive  graphics  commands  used  by  GRA^  At  run  time,  programs  using  this 
libraiy  communicate  (through  fifo  files)  with  another  program  which  translates  the 
grephics  commands  into  grephics  on  the  desired  device.  Each  time  the  program 
runs,  it  may  be  talking  to  a  different  graphics  device.  Rmctions  available  in  the 
rasterlib  include  color  setting  and  choosing,  line  drawing,  mouse  access  (with 
three  types  of  cursor),  raster  drawing  operations,  and  text  drawing.  Generally, 
this  libraiy  is  used  in  coryunction  with  the  displa[y4ib.  Ihe  dspiac^ib  provides 
gr^hics  window  management  routines,  coordinate  conversion  capabilities,  and 
grid  cell  data  to  raster  graphic  conveisions.  See  §23  Display  Graphics  Library 
Ip.  159]  and  §25  Raster  Graphics  Library  Ip.  147]. 


3,3.  Driver  Rrogrammer 

GRASS  programs  are  written  to  be  portable.  To  this  end,  a  tremendous  amount  of 
modularity  is  designed  into  the  system.  Throughout  its  development,  GRASS 
programs  have  become  increasingly  pecialized.  The  original  monolithic  approach 
continues  to  fragment  into  ever  smaller  pieces.  Smaller  pieces  will  allow  future 
developers  and  users  ever  more  variability  in  the  mixing  of  the  tools. 
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TMs  modulahty  has  been  manifested  in  the  graphics  design  A  gn^)hics-oiiented  tool 
connectB,  at  run  time,  to  a  grei^cs  driver  (or  trandator)  program  This  separate 
process  understands  the  standard  grctohics  commands  general  by  the  GRASS  tool, 
and  makes  the  ^piopiiate  graphics  calls  to  a  particular  graphics  device.  Rurh 
graphics  device  avail^le  to  a  user  is  acconqranied  by  a  driver  program,  and  each 
program  understands  the  graphics  calls  of  the  application  poogram  Porting  of  GRASS 
to  a  new  system  primarily  means  tire  development  of  one  new  grEpfaics  driver.  See 
§22  Writing  a  Graphics  Driver  jp.207). 

Those  sites  using  the  digitizing  software  of  GRASS  must  also  provide  driver  routines 
for  their  digitizer.  These  routines,  unlike  the  above  graphics  calls,  are  conpiled 
directly  into  the  digitizir^r  programs.  See  §21  Writing  a  Digitizer  Driver  [p.  2fl5]. 

Similarly,  GRASS  ates  may  wish  to  write  code  to  sigport  different  hardcopy  color 
printers  (in^et,  thermal,  etc.).  See  §23  Writing  a  Paint  Driver  \p.2i5]. 


3.4.  GRASS  Slystem  Desagner 

To  dale,  GRASS  system  design  has  been  done  at  one  location:  USACERL.  One,  ard 
only  one  site  must  be  re^nsible  for  the  design  of  the  system  at  the  database  and 
fundamental  library  level.  As  the  software  is  pitolic  domain,  sites  ate  fiee  to  do  their 
own  work.  However,  the  strength  of  future  (3RASS  releases  depends  on  cooperation 
and  sharing  of  software.  Therefore,  it  is  strorr^y  encouraged  that  database  design 
and  database  library  devciqpnient  be  fuQy  ooortfinated  with  GRASS  staff  at 
USACERL. 


§3 


■  16- 


-  16- 


Chapter  4 

Database  Structure 


This  section  presents  the  programmer  interested  in  developing  new  applications  with 
an  explanation  of  the  structure  of  the  GRASS  databases,  as  implemented  under  the 
UNIX  operating  system. 


41.  IVogramniiig  Interfiaoe 

GRASS  Programmers  are  provided  the  GIS  Library ,  which  inteifaces  with  tiie  GRASS 
database.  It  is  described  in  detail  in  §12  GIS  Libnay  Ip.  63].  Rngrammers  ^uld  use 
this  librai^  to  the  fullest  extent  possible.  In  fact;  a  programmer  will  find  that  use  of 
the  libraiy  will  make  knowledge  of  the  database  stnicti  uunost  unnecessary. 

GRASS  programs  are  not  written  Avith  specific  database  names  or  directories  hard¬ 
coded  into  them  The  user  is  allowed  to  ^ect  the  database  or  change  it  at  will.  The 
database  name,  its  location  within  the  UNIX  file  system,  and  other  related  database 
information  are  stored  as  variables  in  a  hidden  file  in  the  user's  home  directory.^ 
GRASS  programs  access  this  information  via  routines  in  the  GIS  Library.  The 
variables  that  specify  the  database  are  described  briefly  below,  see  §10  Envirorvnertt 
Variables  Ip.  51]  for  more  details  about  these  and  other  environment  variables. 

Note  These  GRASS  environment  variables  may  also  be  cast  into  the  UNIX 
environment  to  make  them  accessible  for  shell  scripts.^  In  tire  discission  bdow,  these 
variables  will  appear  preceded  by  a  dollar  sign  ($).  However,  C  programs  should  rwt 
access  the  GRASS  envirorinent  variables  using  the  UNIX  getenvt )  since  they  do  not 
originate  in  the  UNIX  environmenL  GIS  Library  routines,  such  as  G_geteTw(p.67), 
must  be  used  instead. 


^  This  file  is  ^rassrv  under  GRASS  3.0. 

2  vang  gisenv,  see  §24  Writing  GRASS  Shell  Sbripts  (p.  2291 
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42.  Gisdbase 

The  database  for  GRASS  makes  use  of  die  UNIX  hierarchical  diiectoi^  structure.  Tlie 
top  level  directoiy  is  known  as  GISDBASE.  Users  specify  this  directory  when 
entering  GRASS.  The  full  name  of  das  directoiy  is  contained  in  the  UNIX 
envirorarBnt  variable  $GISDBASE,  and  is  returned  by  library  routine 
G_gisdbase(p.67). 


4.3.  Locations 

Subdirectories  under  the  GISDBASE  are  known  as  locations.  Locations  are 
irxlependent  databases.  Users  select  a  location  when  entering  GRASS  All  database 
queries  and  modifications  are  made  to  this  location  only.  It  is  not  possible  to 
simultaneously  access  multiple  locations.  The  currendy  selected  location  is  contained 
in  the  environment  variable  $LOCATION_NAME,  and  is  returned  by  the  library 
routine  GJocationip.66). 


GISDBASE 

_ 1 _ 

locatioal  locatioa2  locatioaS 


When  users  select  a  location,  they  are  actually  selecting  one  of  the  location  directories. 


4.4  Ma{)se(s 

Subdirectories  under  any  location  are  known  as  mapsets.  Users  select  a  m^rset  when 
entering  GRASS.  New  mapsets  can  be  created  duririg  the  selection  step.  The  selected 
m^set  is  known  as  the  current  mapset  It  is  named  in  the  environment  variable 
$MAPSEr  and  returned  by  G_rnapset(p.  66). 

LOCATION 


m^jaetl  niapset2  mapsetd  ...  PERMANENT 

Modifications  to  the  database  can  only  be  made  in  the  current  mapset  Users  may  only 
select  (and  thus  modify)  a  mapset  that  they  own  (i.e.,  have  created).  However,  data  in 
all  mapsets  for  a  given  location  can  be  read  by  aiiyone  (unless  prevented  by  UNIX  file 
permissions).  See  §4.7  Database  Access  Bides  {p.20]  for  more  details. 

When  users  select  a  mapset,  they  are  ur.tually  selecting  one  of  the  mapset  directories. 

Note.  The  full  UNIX  directory  name  for  the  current  mapset  is 
$GISDBASEy$L(X)ATION_NAME^MAPSET  and  is  retimed  by  the  library  routine 
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GJocatioTkjxithip.  67). 

Note  Each  location  will  have  a  q)ecial  m^Mset  called  FEUMANENT  that  contains 
non-volatile  Hatn  for  the  location  that  aU  users  will  use.  However,  it  also  contains 
some  infonnation  about  the  location  itself  dat  is  not  found  in  other  mapeets.  See 
Perrmnent  Mapset  \p.  19\. 


4.5.  Mapset  Structure 

Mapsets  will  contain  files  and  stdodinectories,  known  as  database  elernents.  hi  the 
diagram  below,  the  elements  are  indicated  by  a  trailing  /. 

MAFSBT 


SEAHCH-PATH  WIND  cats/  cdl/  paint/  windows/ 


4.5.1.  Maiiset  Files 

The  following  is  a  list  of  some  of  the  mapset  files  used  by  GRASS  programs: 


files 

GEOUP  cunent  irnagety  groip 

SEABCELPATH  mapset  seerch  path 
WIND  cunent  window 


This  list  may  grow  as  GRASS  grows.  The  GROUP  file  records  the  curnent  imagery 
grot?)  selected  by  die  user,  and  is  used  only  by  imagery  hmctions.  The  other  two  files 
are  fundamental  to  all  of  GRASS.  These  are  WIND  and  SEARCILPATH. 

WIND  is  the  current  window.  This  file  is  created  when  the  mapset  is  created  and  is 
modified  by  the  uindow  command.  The  contents  of  WIND  are  returned  by 
G_get_uindouip.  77).  See  §9.2  Window  [p. 47]  for  a  discussion  of  die  GRASS  window. 

SE)ARCH-PATH  contaiiis  the  mapset  search  path.  This  file  is  created  and  modified  by 
the  mapsets  command.  It  contains  a  list  of  mapsets  to  be  used  for  finding  dat^biase 
files.  When  users  enter  a  database  file  name  without  specifying  a  specific  mapset,  the 
mapsets  in  this  search  path  are  searched  to  find  the  file.  library  routines  that  look  for 
database  files  use  the  mapset  search  path  to  find  database  files.  See  §4.7.2  Mapset 
Search  Path  fp.20]  for  more  information  about  the  mapset  search  padi 
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46^  Etements 

Subduectories  under  a  n£9)set  are  the  database  elements.  Elements  are  not  created 
when  the  mapeet  is  created,  but  are  created  cb^namically  \^d]en  referenced  by  the 
application  programs.^  Mapset  data  reside  in  files  under  the%  elements. 

The  dynamic  creation  of  database  elements  makes  adding  new  database  elements 
simple  since  no  reconfiguration  of  existing  mapsets  is  required.  However,  the 
programmer  must  be  av.'are  of  the  database  elements  akeady  us^  by  cunendy  existing 
programs  when  creating  new  elements.  FVirdiermore,  as  development  occurs  outade 
USACERL,  guidelines  must  be  developed  for  introducing  new  element  names  to  avoid 
using  the  same  dement  for  two  diverse  purposea 

fVogrammers  using  shell  scripts  must  exercise  care.  It  is  not  safe  to  assume  that  a 
mapset  has  all,  or  any,  database  dements  (especially  brand  new  m^)set5).  Certain 
GRASS  commands  automatically  create  the  element  when  it  is  referenced  (e.g.,  Gask). 
In  general,  however,  elements  are  only  created  whai  a  new  file  is  to  be  created  in  the 
element  It  is  wise  to  explicitly  check  for  the  existence  of  database  elements. 


^  See  ^12.5.6  Ovating  and  Opening  a  New  Database  File  \p.  74]. 
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Here  is  list  of  some  of  the  elements  used  by  GRASS  programs  wiitten  at  USACERL: 


element 

cell 

data  Isiyem  (cdl  files) 

cellfad 

header  files  for  data  la^ro 

cats 

category  ixfomialion  for  data  leyere 

coir 

color  table  for  data  Iqyos 

colr2 

secondary  color  teUes  for  data  Iqjere 

celLnisc 

niacellaneouB  cell  sifinrt  files 

hist 

histoty  information  for  data  Isiyers 

dig 

binary  vector  data 

dig_a8cii 

ascii  vector  data 

dig_8tt 

vector  attribute  si^^rt 

clig_plii6 

vector  topology  st^^rt 

dig.catB 

vector  category  label  support 

reg 

digitizer  point  registration 

bdlg 

binary  dig  files 

dig 

ascii  dig  files 

icons 

icon  files  used  by  paint 

paint 

label  and  corinKit  files  used  by  paint 

grotp 

imagery  groip  support  data 

alteJistB 

site  lists  for  sites  program 

windows 

pre-defined  windows 

COMBINE 

conbine  scripts 

WEIGHT 

weight  sctipte 

Note  The  nsq^set  database  elements  can  be  simple  directoiy  names  (e.g.,  cats,  coir) 
or  multi-level  directoiy  names  (e.g.,  paint/lsbds,  gioip/xyz/si±)gioup/^).  The  library 
routines  that  create  the  element  will  create  the  top  level  directory  and  all  subdirectories 
as  well. 


4.6.  Permaotient  Mapset 

Each  location  must  have  a  PEKMANEIOT  mapset  This  mapset  not  only  contains 
original  map  layers  arxl  vector  files  that  must  not  be  modified,  but  also  two  special 
files  that  are  only  found  in  this  mapset  These  files  are  MYNAME  and 
DEFAULT_WIND  and  are  never  modified  by  GRASS  software. 

MYNAME  contains  a  smgle  line  descriptive  name  for  the  locatioa  This  name  is 
returned  by  the  routine  G^jnynarmip.  66). 

DEFAULT_WIND  contains  the  default  window  for  the  locatioa  This  file  is  used  to 
initialize  the  WIND  file  for  new  mapsets.  The  contents  of  this  file  are  returned  by 
G_get_clefaidtjnindouXp.  78). 
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47.  Database  Access  RideB 

GRASS  database  access  is  controlled  at  the  mapset  level.  There  are  three  sinople 
rules: 

1  A  user  can  select  a  mapset  as  the  current  mapset  only  if  the  user  is  the 
owner  of  the  mapset  directory  (see  ^4.4  M^jsets  (p.  16\). 

2  GRASS  will  create  or  modify  files  oidy  in  the  cunent  mapset 

3  Plies  in  all  mapsets  may  be  read  by  anyone  (see  §4:7.1  Mapset  Search  Path 
|p.20])  unless  prohibited  by  normal  UNIX  file  permissions  (see  §4.7.2  UMX 
File  Pemassiors  \p.20\). 


47.1.  Mapset  Search  Path 

When  users  specify  a  new  data  file,  diere  is  no  ambiguity  about  the  mapset  in  which  to 
create  the  file:  it  is  created  in  die  current  mapset  Pfowever,  when  users  qiecify  an 
existing  data  file,  the  database  must  be  searched  to  find  the  file.  For  example,  if  the 
user  wants  to  display  the  "soils"  cell  file,  the  system  looks  in  the  various  database 
mapsets  for  a  cell  file  named  "soils."  The  user  controls  which  mapsets  are  searched  by 
setting  the  mapset  search  path,  which  is  simply  a  list  of  mapsets.  Each  mapset  is 
examined  in  turn,  and  the  first  "soils"  cell  file  found  is  the  one  that  is  displayed.  Thus 
users  can  access  data  from  other  users’  mapsets  throu^  ds  choice  of  the  search  path. 

Users  set  the  search  path  usiitg  the  mapsets  or  Gmapsets  commands. 

Note  If  there  were  more  than  one  "soils"  file,  the  mapset  search  mechamsm  returns 
the  first  one  found.  If  the  user  wishes  to  override  the  search  path,  then  a  qiecific 
mapset  could  be  specified  alorrg  with  the  file  name.  For  example,  the  user  could 
request  that  "soils  in  PERMANPINT"  be  displayed. 


47.2.  UNIX  File  Pemissicifis 

GRASS  3.0  creates  all  files  with  read/wiite  permission  enabled  for  everyone  and 
directories  with  read/write/search  permission  enabled  for  everyone.'^  This  implies  that 
all  users  can  read  aryone  else’s  data  files.^ 


^  This  nneans  -rw-rw-rw  for  files,  and  drwxrwxrwx  for  diiectories.  It  is  acconplished  by 
setting  the  uma^  to  0  in  all  GRASS  progrEinis. 

It  also  inplies  that  all  users  can  modify  and  nsmove  anyone  else’s  files.  Although  GRASS 
code  won’ t  create  or  modify  files  in  other  users’  mEpsets,  the  dataha.qe  is  wide  open  to  standaid 
UNIX  access.  A  planned  improvement  wilt  be  to  set  the  umask  to  022  so  that  the  pemisaons 
are  -rw-r--r—  for  files  and  drwxr-xr-x  for  directories.  TTiis  will  allow  complete  control  of 
access  to  the  database. 
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Wfaile  there  is  no  mechardsm  cunendy  in  GRASS  to  modify  diese  access  pemnssions, 
access  to  a  ii]e|)6et  can  be  controlled  by  imioviqg  (or  adding)  the  read  and  seaich 
permissions  on  the  mepeet  diiectDiy  its^  using  die  UNIX  chmod  conmand,  without 
adversdy  affecting  GRASS  programs.  Fbr  examjde,  sippose  tibat  die  full  UNIX  name 
of  die  mapeet  is  ^^rassAiata^pearfishAcyz.  To  set  the  pennissionB  so  that  only  the 
mapset  owner  can  access  the  oyz  mapset: 

chmod  0700  /grass/data/speaitifivfyz 

To  reset  the  permissions  so  that  eveiyone  can  read  fiom  die  mapset: 
chmod  0755  /g^aes/dsta/speistiA/xyz 

Waning  Since  the  PERMANEINT  mapset  contains  global  database  information,  all 
users  must  have  read  and  search  access  to  the  PERMANENT  mapset  directoiy.^  Don’ t 
remove  the  read  and  search  permissions  horn  PERMANENT. 


®  PERMANU^  has  the  DEIFAULT_WIND  and  MYNAME  files.  This  is  a  minor  design 
flaw.  Global  database  information  ^uld  be  kept  in  the  database,  bit  not  in  ar^  of  the 
mspeets.  All  rrxpeets  could  then  be  treated  equally. 
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Chaptar  5 

CMdCdlMaps 


This  chapter  provides  an  explanation  of  how  grid  cell  map  layers  are  accommodated  in 
the  GRASS  database.^ 


5.1.  What  is  a  Grid  Ceil  Ms^  hayaf? 

GRASS  grid  cell  map  layers  can  be  conceptualized,  by  die  GRASS  progrBanmer  as 
well  as  the  user,  as  representu^  information  from  a  paper  map,  a  satellite  image,  or  a 
m£p  resultirg  from  the  interpretation  of  other  maps.  Usually  die  infomiation  in  a  map 
layer  is  related  by  a  common  theme  (e.g.,  soils,  or  landcover,  or  roads,  etc.). 

GRASS  grid  cell  data  are  stored  as  a  matrix  of  grid  cells .  Each  grid  cell  covers  a 
known,  rectangular  (generally  square)  patch  of  land.  Each  cell  is  assigned  a  sin^e 
integer  attribute  value  called  the  category  number.  For  exampie,  assume  the  land 
cover  map  covars  a  state  park  The  grid  cdl  in  die  ipper-ldEl  comer  of  die  map  is 
cat^oiy  2  (which  may  represent  prairie);  the  next  grid  cell  to  the  east  is  category  3 
(for  forest);  and  so  on 


lane 

cover 

2 

3 

3 

3 

4 

4 

2 

2 

3 

3 

4 

4 

2 

2 

3 

3 

4 

4 

1 

2 

3 

3 

3 

4 

1 

1 

1 

3 

3 

4 

1 

1 

3 

4 

4 

1  =  urban  3  =  forest 

2  =  praihe  4  =  wetlands 


In  addition  to  the  cell  data  file  itself,  tiiere  are  a  number  of  support  files  for  the  grid 
cell  map  layer.  The  files  which  comprise  a  grid  cell  map  layer  all  have  the  same 
name,  but  each  resides  in  a  difra:ent  database  directory  under  the  mapset  These 

'  Tbe  descriptions  given  here  are  for  GRASS  3.0  date  formats  only.  Revious  formats,  still 
supported  by  GRASS  but  no  longer  generated,  are  described  in  documents  from  earlier  releases 
of  GRASS. 
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database  directories  ate: 


diiBCtorv 

function 

ceU 

grid  cell  data  files 

cellfad 

grid  ceU  header  files 

cats 

map  Iryer  category  information 

coir 

map  lajyer  color  trioles 

coli2 

dtemate  map  layer  color  tables 

list 

map  layer  history  information 

celLiriac 

niacellaneous  map  layer  sipport  information 

For  example,  a  map  layer  named  soils  wodd  have  the  hies  ceWsoils,  ceUhdJsoils, 
colr/soils,  catsIsoUs,  etc. 

Note.  Database  directories  are  also  known  as  database  elerrtertis.  See  ^.4  Mapsets 
\p.  16]  for  a  description  of  database  elements. 

Note.  GIS  Library  routines  which  read  and  write  cell  files  are  described  in  ^12.8  Cell 
File  Processing  [p.soi. 


5^  Grid  Cdl  FQe  Format 

The  programmer  should  think  of  the  grid  cell  data  file  as  a  two-dimensional  matrix 
(i.e.,  an  arrEy  of  rows  and  columns)  of  integer  val\»s.  Each  ceil  is  stored  in  the  file  as 
one  to  four  8-bit  bytes  of  data  An  NrM  cell  file  will  contain  N  rows,  each  row 
containing  M  columns  (or  bytes)  of  data 

The  physical  structure  of  a  cell  file  can  take  one  of  3  formats:  uirompressed, 
conpressed,  or  reclassed. 

Unoonpressed  formoL  The  uncompressed  cell  file  actually  looks  like  an  NjcM 
matrix.  Each  byte  (or  set  of  bytes  for  multi-byte  data)  represents  a  cell  of  the  map 
layer.  The  physical  size  of  the  file,  in  bytes,  will  be  rous*cols*bytes-per-cell. 

Coipressed  format  The  compressed  format  uses  a  ruivleitgth  encoding  schema  to 
reduce  the  amount  of  disk  required  to  store  the  cell  file.  Rurvlength  encoding  means 
that  sequences  of  the  same  data  value  are  stored  as  a  single  byte  repeat  count  followed 
by  a  data  value.  F  the  data  is  single  byte  data,  then  each  pair  is  2  bytes.  F  the  data  is 
2  byte  data,  then  each  pair  is  3  bytes,  etc.  (see  date  format  below).  The 

rows  are  encoded  irxleperxlenlly;  the  number  of  bytes  per  cell  is  constant  within  a  row, 
but  may  vary  from  row  to  row.  Also  F  rurvlength  encoding  results  in  a  larger  row, 
then  the  row  is  stored  norvrun-lerigth  encoded.  And  finally,  since  each  row  may  have 
a  different  length,  there  is  an  index  to  each  row  stored  at  the  beginning  of  the  file. 

Redass  layers  Reclass  mEp  layers  do  not  contain  ary  data,  but  are  refererres  to 
another  map  layer  along  with  a  schema  to  reclassFy  the  categories  of  the  referenced 
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map  layer.  Hie  reclass  ceU  file  itself  contaoie  no  useful  infonuatioa  The  leclass 
infomiation  is  stoied  in  the  cell  header  file. 

Miitit-biyte  date  finiKit  When  the  data  values  in  the  cell  file  lequiie  moie  than  one 
byte,  they  ate  stored  in  h^-entfion  fonnat^^  which  is  to  say  as  abase  256  number  wifii 
the  most  significant  digit  first 

Examples: 


cell  value 

base  256 

868  = 

3*256  +  100  [ 

137304  = 

2*256^  +  24*256  +  88  [ 

174,058,106  = 

10*256®  +  95*25^  +  234*256  +  122  [ 

stored  as 


100 


24  88 


Negative  values  are  stored  as  a  signed  quantity,  i.e.,  with  the  M^iest  bit  set  to  1:^ 


cell  value 

base  256 

stored  as 

-1 

=  -(1) 

11  0  0 

0 

1 

-868 

=  -(3*256  +  100) 

11  0  0 

3 

100 

-137,304 

=  -(2*256®  +  24*256  +  88) 

11  0  2 

24 

88 

-174,058,106 

=  -(10*25^  +  95*25^  +  234*256  +  122) 

1|  10  95 

234 

122 

All  data  values  in 

a  given  row  are  stored  using  the  same 

number  of  bytes.  This  means 

that  if  the  value  868,  which  uses  2  bytes,  occumed  in  a  row  that 
represent  the  largest  data  value,  868  would  be  stored  as  1  olrjlQQl 

uses 

3  bytes  to 

Also,  one  row  may  only  require  2  bytes  to  store  its  data  values,  another  4  bytes,  and 
yet  another  1  byte.  Hie  rows  are  stored  indepandenlly  and  would  be  stored  using  2 
bytes,  4  bytes,  and  1  byte  req;)ectively. 

File  portability.  The  multi-byte  format  described  above  is,  except  for  negative  values, 


-  Tlie  fact  that  tiie  values  are  stored  big-erdian  ^uld  not  be  construed  to  mean  that  the 
machine  architecture  must  also  be  b^-eruMan.  Hb  (mgrams  which  read  cell  files  perfbnn  the 
necessaty  arithmetic  to  construct  the  value.  TTiey  do  NOT  assume  anything  about  byte  ordering 
in  the  cpu. 

*  This  means  that  the  value  is  stored  using  as  many  bytes  as  required  by  an  int^r  on  the 
machine  (usually  4i 
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macfame-independent  If  cell  files  are  to  be  moved  to  a  machine  with  a  different  cpu, 
or  accessed  usiiig  a  heterogeneous  network  file  system  (NFS),  die  foUowmg  guidelines 
should  be  kept  in  mind.  All  3.0  format  cell  files  will  transfer  betwe^  machines,  with 
two  restrictions:  (1)  if  the  file  contains  n^ative  vEdues,  the  size  of  an  int^er  on  the 
two  machines  must  be  the  same;  and  (2)  the  size  of  the  file  must  be  within  the  seek 
capability  of  the  lseek( )  call.'^  Ihe  pre-3.0  compressed  fonnat  is  not  stored  in  a 
machine-independent  format,  and  cannot  generally  be  used  for  inter-machine  transfer. 
It  will  transfer  if  the  two  machines  have  the  same  int^er  and  lopg  int^er  format 


5,3.  Cdl  Header  Fonnat 

The  cell  file  itself  has  no  information  about  how  many  rows  and  columns  of  data  it 
contains,  or  which  part  of  the  earth  tiie  layer  covers.  This  information  is  in  the  cell 
header  file.  The  format  of  the  cell  header  depends  on  whether  the  map  layer  is  a 
regular  map  layer  or  a  reclass  layer. 

Note:  GIS  library  routines  which  read  and  write  the  cell  header  file  are  described  in 
§12.9.1  Cell  Header  File  [p.S9]. 


5.3.1.  Regtdar  Format 

The  regular  map  Isyer  ceil  header  contains  the  information  describing  fire  physical 
characteristics  of  the  cell  file.  The  cell  header  has  the  following  fields; 


cell  header 


proj: 

1 

zone: 

18 

north; 

4660000.00 

south: 

4570000.00 

east: 

770000.00 

west: 

710000.00 

e-w  resol: 

50.00 

n-s  resol; 

100.00 

format: 

0 

compressed: 

0 

proj,  zone 

The  pro/ection  field  specifies  the  type  of  cartographic  projection: 

0  is  unreferenced  x,y  (imagery  data) 

1  is  um 

2  is  State  Hane^ 

Others  may  be  added  in  the  future,  'fhe  zone  field  is  the  projectioii  zone.  In  the 


This  usually  means  that  the  size  of  a  long  integer  on  the  two  machines  is  the  same. 
State  Hane  is  not  yet  fully  suppoited  in  GRASS. 
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example  above,  the  projection  is  UTM,  the  zone  18. 
north,  soutti,  east,  west 

The  geographic  boundaries  of  ttie  cell  file  are  described  by  the  north,  south, 
east,  and  west  fields.  These  values  describe  the  lines  vdiich  bound  the  map  at  its 
edges.  These  lines  do  NOT  pass  throu^  the  center  of  die  cells  at  the  edge  of  the 
map,  but  along  the  edge  of  the  m^  itsdf. 

n-s  resol,  e-w  resol 

The  fields  e-w  resol  and  n-s  resol  describe  the  size  of  each  grid  cell  in  the  map 
layer  in  physical  measurement  units  (e.g.,  meters  in  a  UTM  database).  They  are 
also  called  the  grid  cell  resolution.  The  n-s  resol  is  the  length  of  a  grid  cell  from 
north  to  south.  The  e-w  resol  is  the  length  of  a  grid  cell  from  east  to  west  As 
can  be  noted,  cells  need  not  be  square. 

format 

The  forrmt  field  describes  how  many  bytes  per  cell  are  required  to  represent  the 
grid  cell  data  0  means  1  byte,  1  means  2  bytes,  etc. 

con^ressed 

The  corrpressed  field  indicates  whether  the  grid  cell  file  is  in  compressed  format 
or  not:  1  means  it  is  compressed  and  0  means  it  isri  t  If  this  field  is  missing, 
tiben  the  grid  cell  was  produced  prior  to  GRASS  3.0  and  the  compression 
indication  is  encoded  in  tl£  grid  cell  itself. 

rows,  cols 

The  rows  and  columns  of  the  grid  matrix  are  not  stored  in  the  cell  header.  They 
are  computed  from  the  geographic  boundaries  as  follows: 

rows  =  (north  -  soudi)  /  (ns  resol) 
cols  =  (east  -  west)  /  (ew  leaol) 


5.3.2.  Redaas  Fwrnat 

If  the  cell  file  is  a  reclass  cell  file,  the  cell  header  does  not  have  the  infoimation 
mentioned  above.  It  will  have  the  name  of  the  referenced  cell  file  and  the  cat^oiy 
reclassification  table. 


leclaas  cell  header 


reclass 

name;  county^ 

mapset;  PERMANEIOT 

#5 

fust  category  in  reclass 

1 

5  is  reclassified  to  1 

0 

6  is  reclassified  to  0 

1 

7  is  reclassified  to  1 

0 

8  is  reclassified  to  0 

2 

9  is  reclassified  to  2 
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In  diis  case,  the  library  routines  will  use  this  infomiation  to  open  the  referenced  cell 
file  in  place  of  the  reclass  cell  file  and  coiweit  the  cell  file  data  according  to  tbe 
reclass  scheme.  Also,  the  referenced  cell  header  is  used  as  the  cell  header. 

The  #  as  the  first  character  of  the  fourth  line  in  the  file  indicates  that  this  is  a  3.0 
format  reclass  cell  header  file. 


5.4  Cdl  Category  File  Format 

The  cat^ory  file  contains  the  largest  cat^oiy  value  which  occurs  in  the  data,  a  title 
for  the  map  layer,  an  automatic  label  generation  capability,  and  a  one  line  label  for 
each  category. 


_ category  file _ 

#  5  categories 
title  for  map  Ityer 
<aictormtic  label  formit> 
<aiitomatic  label  parameters> 
0:no  data 

l:de8cription  for  categoiy  1 
2:description  for  categoiy  2 
3:cleacription  for  categoiy  3 
5:deacription  for  categoiy  5 


The  #  as  the  first  character  of  the  first  line  in  the  file  indicates  that  this  is  a  3.0  format 
categoiy  file.  The  nunber  which  follows  it  is  the  largest  categoiy  value  in  the  cell 
file.  next  liiK  is  a  title  for  the  map  Isyer.  The  next  two  lines  are  used  for 
automatic  label  generadon  They  are  used  to  create  labels  for  categories  which  do  not 
have  explicit  labels.  (The  automatic  label  capebility  is  not  normally  used  in  most  map 
layers,  in  which  case  the  format  line  is  a  blank  line  and  the  parameters  line  is: 
0.0  0.0  0.0  0.0.)  Cat^oiy  labels  follow  on  the  remaining  lines.  The  format  is 
cat:  label. 

The  first  four  lines  of  the  file  are  required.  The  remaining  lines  need  only  appear  if 
categories  are  to  be  labeled. 

Note.  GIS  Library  routines  which  read  and  write  the  cell  categoiy  file  are  described 
in  ^12.9.2  Cell  Category  FUe  [p.9il. 


5.5.  Cell  Colcr  Table  Fonnat 

The  color  table  contains  one  line  of  a  color  description  for  each  category  of  data, 
irrludirig  the  "no  data"  categoiy.  The  colors  are  represented  as  levels  of  red,  green, 
and  blue,  where  0  represents  the  lowest  intensity  and  255  represents  the  highest 
intensity. 
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color  tdble  file 


#4  first  color 

266 

255 

265 

0 

128 

128 

200 

128 

40 

255 

0 

0 

0  265 

255 

0 

color  for  category  0 
color  for  category  4 
color  for  category  5 
color  for  category  6 
color  for  category  7 
color  for  category  8 


The  #  as  the  fust  character  of  the  fust  line  in  tire  file  indicates  that  this  is  a  3.0  fonnat 
color  file.  The  number  which  follows  is  the  first  data  value  which  has  a  color  (and 
should  be  the  lowest  non-zero  cat^oiy  value  in  the  cell  file).  The  next  line  is  the 
color  for  cat^oiy  0.  The  remaining  lines  are  the  colors  for  the  other  categories.  There 
are  3  columns  representing  the  red,  green,  and  blue  levels  respectively.  If  all  3  values 
are  identical  (i.e.,  a  grey  scale  color),  only  the  red  value  need  be  present 

Note  that  the  color  file  fonnat  is  a  modest  attempt  to  allow  color  tables  for  files  like 
elevation,  which  have  (heir  lowest  non-zero  data  value  above  1  (often  above  1000).  In 
these  cases  the  color  table  doesri  t  have  to  start  with  1  and  create  unused  colors. 

Note.  GIS  Library  routines  which  read  and  write  the  cell  color  table  are  described  in 
^12.9.3  Cell  Color  Tithfe  [p.94]. 


5.6.  Cell  Ifistny  File 

The  histoiy  file  contains  historical  infoimation  about  the  cell  file;  creator,  date  of 
creation,  comments,  etc.  In  most  applications,  the  programmer  need  not  be  concerned 
with  the  histoiy  file.  It  is  genererted  automatic£^y  along  with  the  cell  file.  The 
GRASS  layer.info  program  allows  the  user  to  view  this  information,  and  the  support 
program  allows  the  user  to  ipdate  it 

Note  GIS  library  routines  which  read  and  write  the  cell  histoiy  file  are  described  in 
^12.9.4  Cell  Hstory  File  fp.S®]. 


5.7.  Cell  Range  File 

The  range  file  contains  the  minimum  and  maximum  values  which  occur  in  a  cell  file. 
It  is  generated  automatically  for  all  new  cell  files.  This  file  lives  in  the  cell_misc 
element  as  ’’cell_jnisc/nameAurge"  where  name  is  the  related  cell  file  name. 

It  contains  one  line  with  four  integer  values.  These  represent  the  minimum  and 
maximum  negative  values,  and  the  minimum  and  maxmimum  positive  values  in  the 
cell  file.  If  there  are  no  negative  values,  then  the  first  pair  of  numbers  will  be  zero.  If 
there  are  no  positive  values,  then  the  second  pair  of  numbers  will  be  zero. 
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Nbte.  GIS  Library  routines  which  read  and  write  the  cell  range  file  are  described  in 
§22.9.5  Cell  Hange  File  [p.99]. 
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Chapter  6 

Vecfccr  M^k 


This  chapter  provides  an  explanation  of  how  vector  map  layers  are  accommodated  in 
the  GRA^  dkabase. 


6.1.  What  is  a  Vectcr  Map 

GRASS  vector  meps  are  stored  in  an  arc-node  representation,  consisting  of  non- 
intereecting  curves  called  arcs.  An  arc  is  stored  as  a  series  of  x,y  coordinate  pairs.^ 
The  two  end-points  of  an  arc  are  called  nodes.  Two  consecutive  pairs  define  an  arc 
segment.  ^ 

The  arcs,  dther  singly,  or  in  combination  with  others,  fonn  higher  level  map  features: 
lines^  (e.g.,  roads  or  streams)  or  areas ^  (e.g.,  farms  or  forest  stands).  Arcs  that  form 
linear  features  are  sometimes  called  lines,  and  arcs  that  outline  areas  are  called  area 
edges  or  area  lines.  ^ 

Each  map  feature  is  assigned  a  single  int^er  attribute  value  called  the  category 
number.  For  exanple,  assume  a  vector  file  contains  land  cover  infonnation  for  a  state 
paifc  One  area  may  be  assigned  category  2  (perhaps  representing  prairie);  another  is 
assigned  category  3  (for  forest);  and  so  on.  Another  vector  file  which  contaiis  road 
information  may  have  some  roads  assigned  category  1  (for  paved  roads);  other  roads 
may  be  assigned  category  2  (for  gravel  roads);  etc.  See  §5.2  What  is  a  Grid  Cell  Map 
Layer?  Ip.  23]  for  more  information  about  GRASS  category  values. 

*  Fbr  this  reason  arcs  are  also  called  vectors. 

2  Arc  segnents  are  sometinies  called  liiie-segments. 

A  line  here  does  not  mean  a  straight  line  between  two  points.  It  only  means  a  linear 
feature. 

Areas  are  also  called  poisons.  The  GRASS  vector  format  does  not  store  the  polygons 
explicitly.  They  are  constructed  by  finding  toe  {particular  arcs  which  forai  the  polygon 
perimeter. 

Obviously,  there  is  sonre  confusion  in  toe  GIS  vector  terminology.  Tlas  is  pertly  due  to 
use  of  terms  that  have  a  common  meaning  as  well  as  a  mathematical  meaning.  Vector 
termLxplogy  is  a  subject  for  much  debate  in  the  GIS  worid. 
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A  vector  map  layer  is  stored  in  a  number  of  data  files.  The  files  which  comprise  a 
single  vector  map  layer  all  have  ttie  same  name,  but  each  resides  in  a  different 
database  directory  under  the  mapset®  These  database  directories  are: 


diiectorv 

function 

dig 

binary  £bt:  file 

dig_aacii 

ascii  arc  file 

dig_att 

vector  category  attribute  file 

dig_catB 

vector  category  labels 

dig_plu8 

vector  index/pointer  file 

reg 

digitizer  registration  points 

For  example,  a  map  layer  named  soils  would  have  the  files  dig/soils,  digjsttlsoils, 
dig^lus/soUs,  (Mgjisculsoils,  digj:ats/soils,  reg/soils,  etc. 

Note.  Vector  files  are  also  called  cligU  files,  since  they  are  created  and  modified  by 
the  GRASS  digitizing  program 

Note  When  referring  to  one  of  the  vector  m^  l^er  files,  the  directory  name  is  iBed. 
For  example,  the  file  under  the  dig  directory  is  called  the  dig  file. 

Note  Library  routines  which  read  and  write  vector  files  are  described  in  §23  Dig 
Library  \p.  123\. 


6,2.  Asdi  Arc  File  Format 

The  arc  information  is  stored  in  a  binary  format  in  the  dig  file.  The  format  of  this  file 
is  reflected  in  the  ascii  representation  stored  in  the  digjascii  file.  It  is  the  ascii 
version  which  is  described  here.^ 


^  Database  directories  are  dso  called  elements.  See  §4.4  Mapsets  [p.  IS]  for  a  description  of 
database  elements. 

^  Hb  programs  inport. to. uect,  a.b.vect,  and  b.a.vect  convert  between  the  ascii  and  binary 
formats. 
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The  dig^pscii  file  has  two  sectionB:  a  header  section,  and  a  section  containing  the  arca 


6.2.1.  Header  Secticn 

The  header  contains  histoiical  information,  a  desciiption  of  the  wap,  and  its  location  in 
the  umverse.  It  consists  of  fourteen  entries.  Each  entry  has  a  label  identifying  the 
type  of  information,  followed  by  the  information.  The  format  of  the  header  is: 


label 


fonnat 


deaeription 


ORGANIZATION: 
DIGIT  DATE 
DIGIT  NAME 
MAP  NAME 
MAP  DATE 
OTHER  INFO: 
MAP SCALE 
ZONE 

WEST  EDGE 
EAST  EDGE 
SOUTH  EDGE 
NORTH  EDGE 
MAP  THRESH; 
VERTL 


text  (meK  29  characters)’* 
text  (max  19  charactera)* 
text  (max  19  charactera)* 
text  (max  40  charactera)’* 
text  (max  10  characters)’* 
text  (max  72  characters)’* 
integer 
integer 

teal  nutriber  (dodble) 
teal  nundber  (double) 
teal  number  (double) 
teal  nutiber  (double) 
teal  nutiber  (double) 

(no  data) 


oiganizadon  tinat  digitized  the  data 
date  the  data  was  digitized 
person  vbo  digitized  the  data 
tide  of  the  original  source  m^ 
date  of  the  original  source  map 
other  comments  about  the  map 
scde  of  the  origin^  source  m^ 
zone  of  the  map  (e.g.,  ITTM  zone) 
western  edge  of  the  entire  mapt 
eastern  edge  of  the  entire  mapt 
southern  edge  of  the  entire  m^t 
northern  edge  of  the  entire  mapt 
digitizing  resolution  t 
maiks  the  end  of  the  header  section 


The  labels  start  in  column  1  and  continue  through  column  14.  Labels  are  l^)percase, 
left-justified,  end  with  a  colon,  and  blank-padded  to  column  14,  The  information  starts 
in  column  15.  For  example: 


*  Currentiy,  GRASS  programs  which  read  the  header  infoimation  are  not  tolerant  of  text 
tields  which  exceed  these  limitB.  If  the  limits  are  exceeded,  the  ascii  to  binaiy  conversion  will 
probably  fail. 

t  The  edges  of  the  map  describe  a  window  which  should  enconpass  ail  tiie  data  in  the 
vector  file. 

t  The  MAP  THRESH  is  set  ly  the  digit  program,  ff  the  data  comes  from  outside  GRASS, 
this  field  can  be  set  to  0.0. 
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ORGANIZATON: 

US  Amy  CERL 

DIGIT  DATE 

03A8/88 

DIGIT  NAME 

grass 

MAP  NAME 

IMiena,  IL. 

MAP  DATE 

1976 

OTHER  INFD: 

USGS  sw/4  ubana  IS*  quad.  N4000-W8807.5/7.5 

MAP SCALE 

24000 

ZONE 

16 

WEST  EDGE 

383000.00 

EAST  EDGE 

404000.00 

SOUTH  EDGE 

4429000.00 

NORTH  EDGE 

4456000.00 

MAP  THRESH 
VERTL 

0.00 

6w2J2.  Arc  Section 

The  arc  information  appears  in  the  second  section  of  the  dig_pscu  file  (following 
VERU:  which  maiks  the  end  of  the  header  section).  Each  arc  conasts  of  a 
description  entry,  followed  by  a  series  of  coordinate  pairs.  The  description  specifies 
both  the  type  of  arc  (A  for  area  edge,  or  L  for  line®),  and  the- number  of  points 
(coordinate  pairs)  in  tire  arc.  Then  the  points  follow. 

For  example: 

A  5 

4434456.04  388142.16 

4434446.65  388202.64 

4434407.49  390524.38 

4434107.06  390523.59 

4433326.51  390526.48 

L  3 

4434862.31  392043.33 

4434872.42  394662.14 

4434871.44  398094.75 

A  3 

4454747.38  396579.60 

4454722.69  393539.73 

4454703.68  390786.90 

In  this  example,  the  first  arc  is  an  area  edge  and  has  5  points.  The  second  arc  is  part 
of  a  linear  feature  and  has  3  points.  The  third  arc  is  another  area  edge  and  has  3 
points. 

The  arc  description  has  the  letter  A  or  L  in  the  first  column,  followed  by  at  least  one 

^  (Jther  types  may  be  added  in  the  future. 
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spece,  and  followed  by  the  nucnber  of  points.^ 

Point  entries  start  with  a  space,  and  henre  at  least  one  q)ace  between  two 
coonfinate  values.^® 

Note  The  points  are  stored  as  y,x  (i.e.,  north,  east),  which  is  the  reverse  of  the  way 
GRASS  usi^y  represents  geographic  coordinates. 

Note  If  the  program  has  deleted  an  arc,  the  arc  type  will  be  rqrresented  using  a 
lower  case  letter  (i.e.,  I  instead  of  L,  a  instead  of  A).  Of  course,  das  will  only  be 
manifest  when  a  binary  dig  file  with  a  deleted  arc  is  converted  to  the  ascii  cdgjxscii 
file. 


6,3.  Vector  CategOKy  Attribute  File 

As  was  mentioned  in  §6.i  What  is  a  Vector  Map  Layer'?  (p.3l],  each  feature  in  the 
vector  atep  layer  has  a  category  nutrher  assigned  to  it  The  cat^ory  rarmber  for  each 
map  feature  is  not  stored  in  the  file  itsdf,  but  in  tire  dig^att  file. 

The  dig^att  file  is  an  ascii  file  that  has  multiple  entries,  each  with  the  same  format 
Each  entry  refers  to  one  map  feature,  and  ^recifies  the  feature  type  (area  or  line),  an 
x,y  marker,  and  a  category  nunJoer. 

Fbr  example: 

A  389668.32  4433900.99  7 

L  396103.96  4434881.19  2 

In  this  example,  an  area  feature  is  assigned  category  7,  and  a  linear  feature  is  assigned 
cat^ory  2. 

The  x,y  marker  is  used  to  find  the  msp  feature  in  the  file.  It  must  be  located  so 
that  it  uniquely  identifies  its  related  map  feature.  In  particular,  an  area  marker  must  be 
inside  the  area,  and  a  line  marker  must  be  closer  to  its  related  line  than  to  any  other 
line  (preferrably  on  the  line)  arxi  not  at  a  node. 

If  multiple  entries  identify  the  same  m^  feature,  only  one  will  be  used  (currenlly  the 
last  one). 

A  map  feature  which  has  no  entry  in  this  file  is  considered  to  be  unlabeled.  This 
means  that  during  the  vector  to  raster  conversion  (i.e.,  vect.to.ceU),  urdabeled  areas  will 
convert  as  category  zero,  and  unlabeled  lines  will  be  ignored 

®  This  can  be  writt^  with  the  Fbrtan  format:  Al,lXd4. 

*0  Theae  can  be  written  with  the  Fbrtran  format;  2(1XJ^12.2). 


§6  Vector  Maps 


-36- 


-36- 


The  format  of  this  file  is  raolher  strict,  and  is  described  in  the  following  table: 


colunns 

date 

1 

Type  of  map  feature  (A  orD* 

2-3 

spaces 

4-15 

Easting  (x)  of  the  marker,  rig^  justified 

16-17 

spaces 

18-29 

Northing  (y)  of  the  marker,  right  justified 

30-31 

^taces 

32-39 

Category  number,  right  justified 

40-49 

spaces 

50 

newline  t 

This  format  is  required  by  programs  which  modify  the  vector  map  (e.g.,  digit). 
Rngrams  which  only  read  the  vector  map  accept  a  looser  format:  the  feature  type 
must  start  in  column  1;  the  items  must  be  separated  by  at  least  one  space;  and  die 
entries  must  be  less  than  50  characters.  Also,  die  program  support.vect  will  convert 
the  looser  format  to  dns  stricter  format 

Note.  The  matker  is  specified  as  x,y  (i.e.,  east,  nordi),  which  is  the  way  GRASS 
usually  represents  geographic  coordinates,  but  which  is  reverse  of  the  way  the  arcs  are 
stored  in  the  <%_i3scu  file. 


6.4  Vector  Cati^gory  Labd  FQe 

Eiach  category  in  the  vector  map  layer  may  have  a  one-line  description  These 
cat^ory  labels  are  stored  in  die  digjcats  file.  The  format  of  this  file  is  identical  to  the 
grid  cell  category  file  described  in  §5.4  Cell  Category  File  Format  \p.28\,  and  the 
reader  is  referred  to  that  section  for  details. 

Note  The  program  support.vect  allows  the  user  to  enter  and  modify  tiie  vector 
cat^oiy  labels.  The  program  vect.to.cell  copies  the  dig_cats  file  to  the  cdl  category 
file  during  the  vector  to  raster  conversion 

Note.  Library  routines  which  read  and  write  the  digjcats  file  are  described  under 
^12.10.6  Vector  Category  File  [p.KX  . 


*  Other  types,  such  as  point,  may  be  allowed  in  the  fijlune. 

^  UNIX  text  files  are  teminaled  with  a  newline.  Therefore,  each  entry  will  appear  as  49 
characters.  The  entire  file  size  should  be  a  multiple  of  50. 
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&5.  VectiGr  and  Paintar  File 

The  (£g_j^  file  contains  infoimation  that  accderates  vector  queriea  It  is  cieated  by 
tl£  program  builcLvect  (which  is  run  by  digU  when  a  vector  file  is  created  or  modified, 
and  by  support.vect  at  user  request)  from  the  data  in  the  and  dig_£tt  files. 

For  this  reason,  and  suxe  the  internal  structure  of  the  dig_pk&  file  is  complex,  the 
format  of  this  fUe  will  not  be  described. 


6.6.  Digitizar  R^istration  Points  FQe 

The  reg  file  is  an  ascii  file  used  by  the  digji  progreon  to  store  map  r^stration  control 
points.  Each  map  r^straition  point  has  one  entry  with  the  easting  and  northing  of  the 
m^  control  point  R)r  exan^le: 

383000.000000  4429000.000000 

383000.000000  4456000.000000 

404000.000000  4456000.000000 

404000.000000  4429000.000000 

Note  This  file  is  used  by  digit  only.  It  is  mt  used  by  ary  other  program  in  GRASS. 


6.7.  Vector  Topology  Rules 

The  following  rules  spply  to  the  vector  data: 

1  Arcs  should  not  cross  each  other  (i.e.,  arcs  which  would  cross  must  be  split  at 
tiheir  intersection  to  form  distinct  arcs). 

2  Arcs  which  share  nodes  must  end  at  exactly  the  same  points  (i.e.,  must  be 
snapped  together).  TTiis  is  particularly  in^rtant  since  nodes  are  not  explicitly 
represented  in  the  arc  file,  but  only  implicidy  as  endpoints  of  arcs. 

3  Common  boundaries  should  appear  only  once  (i.e.,  should  not  be  double 
digitized). 

4  Areas  must  be  explictly  closed.  This  means  that  it  must  be  possible  to  complete 
each  area  by  following  one  or  more  area  edges  that  are  connected  by  common 
nodes,  arxl  tiiat  such  tracirigs  result  in  closed  areas. 

5  It  is  recommended  that  area  features  arxl  linear  features  be  placed  in  separate 
layers.  However  if  area  features  arxl  linear  features  must  ^pear  in  one  layer, 
comnx)n  boimdaries  should  be  digitized  only  orxe.  An  area  edge  that  is  also  a 
line  (e.g.,  a  road  which  is  also  a  field  boundary),  should  be  digitized  as  an  area 
edge  (i.e.,  arc  type  A)  to  complete  the  area  The  area  feature  should  be  labeled 
as  an  area  (i.e.,  feature  type  A  in  the  digjatt  file).  Additionally,  the  common 
bourxlary  arc  itself  (i.e.,  the  area  edge  which  is  also  a  line)  should  be  labeled  as  a 
line  ( i.e.,  feature  type  L  in  the  digjxtt  file)  to  identify  it  as  a  linear  feature. 
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Iiiyorting  Vector  Ffleg  Into  GRASS 

The  following  files  are  required  or  recommended  for  importing  vector  files  from  other 
systEDos  into  GRASS; 

dig_ascu 

The  dUgjiscii  file,  desciibed  in  §6.2  Ascii  Arc  File  Format  \p.32],  is  requirod. 
digjxtt 

The  dig_ptt  file,  described  in  §6,3  Vector  Category  Attribute  File  lp.35],  is 
essentially  required.  While  the  dig_ascii  file  alone  is  sufficient  for  simple  vector 
display,  the  dSgjjtt  file  is  reqvdred  for  vector  to  cell  convasion,  as  well  as  more 
sophisticated  vector  query. 

dig_cats 

'Hie  (Sgjcats  file,  described  in  §6,4  Vector  Category  Label  File  [p.56],  while  not 
required,  allows  m^  feature  descriptions  to  be  imported  as  well. 

Note.  The  (£g_plus  file,  described  in  §6.5  Vector  Index  and  Pointer  File  \p.37],  is 
created  by  the  GRASS  program  irrport.to.vect  when  converting  the  dig_ascii  file  to 
the  binary  dig  file. 
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Chapter  7 

Point  Data:  Site  list  FQes 


This  section  describes  how  point  data  is  cinrentiy  acconmodated  in  the  GRASS 
database. 


7.1.  What  is  a  She  List? 

Point  data  is  cnmendy  stored  in  ascii  files  called  site  lists  or  site  files.  These  files  are 
used  by  the  sites^  program,  which  was  developed  as  an  application  within  GRASS  to 
aid  in  ancheological  site  predictive  modeling.  The  site  list  files  were  designed  for  use 
by  this  program,  but  have  since  become  the  principal  data  structure  for  point  data.^ 


7.2.  She  FQe  Format 

Site  files  are  ascii  files  stored  under  die  siteJists  diabase  element^  The  fonnat  of  a 
site  file  is  best  explained  by  example: 

name  jsanple 
descisampde  site  list 
728220 1 5182440 1 site  27 
727060 15181710 1 site  28 
725500 15184000  late  29 
719800 15187200 1 site  30 


naome 

This  line  contains  the  name  of  the  .site  list  file,  and  is  printed  on  all  the  reports 
generated  by  the  sites  program.  The  word  nanne  must  be  all  lower  case  letters. 


It  is  permissible  for  this  line  to  be  missing,  ance  the  sites  program  will  add  a 
name  record  using  the  name  of  the  site  list  file  itself. 


'  The  GRASS  User’s  RefererKe  h/kmual,  19SS  contains  a  comfiete  description  of  the  sites 
capability. 

Other  GRASS  iMograms  which  read  ate  lists  inclixle  Gsites,  dsites  and  paint. 

^  See  §4.5.2  EtemerOs  \p.  ik\  for  an  explanation  of  database  elements. 
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desc 

This  line  contaiiis  a  description  of  the  site  list  file,  and  is  printed  on  all  the 
reports  generated  by  the  sates  program.  The  word  desc  must  be  all  lower  case 
letteis. 

It  is  also  pemissible  for  this  line  to  be  missing,  in  which  case  the  site  list  will 
have  no  descriptioa 

points 

The  remaining  lines  are  point  records.  Each  site  is  described  by  a  point  record. 
The  fomiat  for  tins  record  is: 

east  Inordi  |  description 

The  east  and  north  fields  represent  the  geographic  coordinates  (eastiiig  and 
northing)  of  the  site.  The  description  field  provides  a  one  line  text  description 
(label)  of  the  site,  and  is  optional. 

comments 

Blank  lines,  and  lines  beginning  with  #,  are  accepted  (and  ignored). 

Note.  The  character  |  is  used  to  separate  tide  fields  in  the  records. 


73,  FVogranmifaig  IntoiGEioe  to  Site  Files 

The  programming  interface  to  the  site  list  files  is  described  in  §i2.1I  She  List 
Processing  Ip.  105]  and  the  programmer  should  refer  to  that  section  for  details. 
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Chapter  8 

Image  Data:  GroiqK 


This  chapter  provides  an  explanation  of  how  imageiy  data  are  acconnxiodated  in  the 
GRASS  database. 


8.1.  Introduction 

Remotely  sensed  imgges  are  cs^Jtured  for  computer  processng  by  satellite' or  aiibome 
sensois  by  hlteiing  radiation  emanating  from  the  image  into  various  electromagnetic 
waveleng^  bands,  converting  the  overall  intenafy  for  each  band  to  digital  format,  and 
storing  the  values  on  con^niter  compatible  media  such  as  magnetic  tape.  Color  and 
color  infra-red  photographs  are  optically  scanned  to  convert  the  red,  green,  and  blue 
wavelength  ban^  in  the  photograph  into  a  digital  format  as  well. 

The  digitial  format  used  by  image  data  is  basically  a  raster  format  GRASS  imagery 
programs^  which  extract  image  data  from  magnetic  tape  extract  the  band  data  into  cell 
files  in  a  GRASS  database.  Each  band  becomes  a  separate  cell  file,  with  starxlard 
GRASS  data  layer  support,  aond  can  be  displayed  and  analyzed  just  like  any  other  cell 
file. 

However,  since  tire  band  files  are  extracted  as  individual  cell  files,  it  is  necessary  to 
have  a  mechanism  to  maintEdn  a  relationship  between  band  files  from  the  same  inrage 
as  well  as  cell  files  derived  from  the  band  files.  The  GRASS  database  structure 
accorrplishes  this  goal. 


8.2.  What  is  a  Group? 

The  group  is  a  database  mechanism  which  provides  the  following: 

( 1 )  A  list  of  related  cell  files. 

(2)  A  place  to  store  control  points  for  image  registration  and  rectification, 
arxi 


’  See  §S.4  Irragery  Prograns  Ip.  45]  for  a  list  of  the  nrs^or  GRASS  imagery  programs. 
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(3)  A  place  to  store  spectral  signatures,  image  statistics,  etc.,  which  are 
ne^ed  by  image  classification  proceedures. 


8.2.1.  A  List  of  Cdl  Files 

The  essential  feature  of  a  groi^  is  diat  it  has  a  list  of  cell  files  that  belong  in  the 
groip.  These  can  be  band  data  extracted  imm  the  same  data  tape,  or  cell  files  derived 
from  the  original  band  files.^  Therefore,  the  groiq)  provides  a  convenient  "handle"  for 
related  image  data;  i.e.,  refening  to  die  group  is  equivalent  to  refenipg  to  all  the  band 
files  at  once. 


8.2.2.  Image  Registration  and  Rectification 

The  group  also  provides  a  database  mechanism  for  image  r^stration  and  rectification 
The  band  data  extracted  from  tapes  are  usually  unregistered  data  This  means  that  the 
GRASS  software  does  not  know  the  Earth  coordinates  for  pixels  in  the  imqge.  The 
only  coordinates  known  at  the  time  of  extraction  are  the  columns  and  the  rows  relative 
to  the  way  the  data  was  stored  on  the  tape. 

Image  registration  is  the  process  of  associating  Earth  coordinates  widi  pixels  on  the 
imqge.  Image  rectification  is  the  process  of  converting  the  imqge  files  to  the  new 
coordinate  system  based  on  the  registration 

Image  r^stration  is  applied  to  a  group,  rather  than  to  individual  cell  files.  The  user 
displays  any  of  the  cell  files  in  a  group  on  the  grEpfaics  monitor  and  then  maiks  control 
points  on  the  image,  asagning  Earth  coordinates  to  each  control  point  The  control 
points  are  stored  in  the  group,  allowing  all  related  group  files  to  be  registered  in  one 
step  rattier  than  individually. 

Image  rectification  is  applied  to  individual  cell  files,  with  the  control  points  for  the 
group  used  to  control  the  rectification.  The  rectified  cell  files  are  placed  into  another 
database^  known  as  the  target  database.  Rectification  can  be  applied  to  any  or  all  of 
the  cell  files  associated  with  a  group. 


8.2.3.  Image  Classificaticn 

Image  classification  methods  process  all  or  a  subset  of  the  band  files  as  a  unit  For 
example,  a  clustering  algorithm  generates  spectral  signatures  which  are  then  used  by  a 
maximum  likelihood  classifier  to  produce  a  landcover  map. 


Derived  cell  fUee  can  be  the  results  of  image  classification  piocedures  such  as  clustering 
and  maxirrum  likelihood,  or  band  ratios  formed  using  Gmapcalc,  etc. 

Either  a  projected  database,  such  as  ITTM,  or  an  unregistered  database,  if  the  image  is 
being  registered  to  ar»ther  image. 
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Sometimes  only  a  sdbset  of  the  band  files  aare  used  dinii^g  imagp  clasafication.  Ihe 
signatures  must  be  associated  only  with  the  cell  files  actually  used  in  the  analysia 
Therefore,  wifinn  a  group,  subgroiqjs  can  be  formed  which  list  only  the  band  fil^  to 
be  "si±>grov?)ed"  for  classification  puiposes.  The  signatures  are  stored  wi*h  the 
subgroiq).  Multiple  subgroups  can  be  created  within  a  group,  which  aiiows  different 
classifications  to  be  run  with  different  combinations  of  band  files. 


8,3.  The  Graiq)  Sbructure 

Groups  live  in  the  GRASS  database  under  the  grocp  database  element^  The  structure 
of  a  group  can  be  seen  in  the  following  diagram.  A  trailing  /  indicates  a  directory. 

grotqy 


nmiDEiySO/  nhfgijunSS/  nhap.octSS/  tm.qr88/ 


REF  POINTS  TARGiJr  subgroup/ 

In  this  example,  the  groups  are  named  rres.rmy80,  nhapJunSS,  etc.^  Note  that  each 
group  is  itself  a  directory.  Each  group  contains  some  files  (RBF,  POIMS,  and 
TAEGET),  and  a  subdirectory  (subgroup ). 


8.3.1.  The  REF  File 

The  REF  file  contains  the  list  of  cell  files  associated  with  the  group.  The  format  is 
illustrated  below; 


tmaprSS.l 

grass 

tmapr68.2 

grass 

tmspr68.3 

grass 

tmapr68.4 

grass 

tmapr88.5 

grass 

tmapr88.7 

gaes 

Each  line  of  this  file  contairB  the  name  and  m^)set  of  a  cell  file.  In  this  case,  there 
are  six  cell  files  in  the  group:  tmaprSS.l,  trrtapr882,  tmapr88.3,  tmapr88.4, 
tmapr88.5  and  tmaprSS.l  in  mapset  gnoss .  (Resurmably  these  are  bands  1-5  and  7 
from  an  April  88  Landsat  Thematic  Mspper  image.) 

See  §4.5-2  Etermnts  ip.  /«]  for  an  explanation  of  databaaR  elements. 

Tlie  groip  nannes  anp  chosen  by  the  user. 
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aa2.  TlKPOINrSFUe 

The  POINTS  file  contains  the  image  r^stration  control  points.  This  file  is  created  and 
modfied  by  the  i.points  program.  Its  fomiat  is  illustrated  below. 


image 

ta;get 

rfefiis 

east 

nordi 

east 

north 

(l=ok) 

504.00 

-2705.00 

379145.30 

4448504.56 

1 

458.00 

-2713.00 

378272.67 

4448511.67 

1 

2285.80 

-2296.00 

415610.08 

4450456.17 

1 

2397.00 

-2564.00 

417043.22 

4444757.65 

0 

2158.00 

-2944.00 

411087.79 

4438210.97 

1 

2148.00 

-2913.00 

410834.61 

4438656.18 

0 

2288.80 

-2336.20 

415497.19 

4449671.77 

1 

The  lines  which  b^;in  with  #  are  comment  lines.  The  first  two  columns  of  data  (under 
image)  are  the  column  (i.e.,  east)  and  row  (i.e.,  north^)  of  the  registration  control 
points  as  maiited  on  die  image.  The  next  bvo  columns  (under  target )  are  the  east  and 
north  of  the  marked  points  in  the  target  database  coordinate  system  (in  this  case,  a 
UTM  database).  The  last  column  (under  status )  indicates  whedier  or  not  the  control 
point  is  well  placed.^  (If  it  is  ok,  then  it  will  be  used  as  a  valid  registration  point 
Otherwise,  it  is  sin^y  retained  in  the  file,  but  not  used.) 


aaa  The  target  File 

The  TARGET  file  contains  the  name  of  the  target  database;  i.e.,  the  GRASS  database 
mapset  into  which  rectified  cell  files  will  be  created.  The  TARGET  file  is  written  by 
i.target  and  has  two  lines: 


spearfi^ 

grass 


The  first  line  is  the  GRASS  location  (in  this  case  spearfish),  and  the  second  is  a 
m^iset  within  the  location  (in  this  case  grass ). 


a3.4  SubgroiqK 

The  subgroup  directory  under  a  groiq)  has  the  following  structure: 


Note  that  the  row  values  are  negative.  This  is  becaiee  GRASS  requires  ttie  northingB  to 
increase  from  so<ith  to  north.  Negative  values  accomplish  this  while  preserving  the  row  value. 
The  true  image  row  is  the  absolute  value. 

^  The  user  makes  this  decision  in  i.points. 
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cdagroiq)/ 

_ I _ 

I  I  I 

123/  234/  1357/ 

1357/ 


REF  ag/ 


cluster.l  cluster.2 

In  this  example,  the  sifcgroi^K  are  named  123,  234,  1357,  etc.®  Within  each 
subgroi?),  there  is  a  REF  file  and  a  sig  diredniy.  The  REF  file  would  list  a  subset  of 
cell  files  from  the  group.  In  this  example,  it  could  look  like; 


tm.apr68.1 

grass 

tm.apr88.3 

grass 

tm.apr68.5 

grass 

tm.apr68.7 

grass 

mdicating  that  the  subgroip  is  composed  of  bands  1,  3,  5,  and  7  fiiom  the  April  1988 
TM  scene.  The  files  cluster.l  and  cluster 2^  under  the  directoiy  contain  spectra/ 
signature  information  (i.e.,  statistics)  for  tHs  combination  of  band  filea  The  files 
were  generated  by  different  runs  of  the  clustering  program  Lchister. 


8.4  Imagay  Rrograiiis 

Tl«  following  is  a  list  of  some  of  the  imageiy  programs  in  GRASSY  with  a  brief 
description  of  what  they  do.  Refer  to  the  GRASS  User's  Reference  Manual  for  more 
detaila 


**  The  eitbgroip  names  are  chosen  by  the  user  (hopefully  reflecting  the  contents  of  the 
subgroup). 

^  Again,  these  file  names  are  chosen  by  the  user. 
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image  extraction 

i.tBpe.n]a8  1  ^undaat  Multi-tipectral  Scunner  data 

i.tape.tm  Landsat  Thematic  Mapper  data 

i.tBpe.other  other  fonnate,  such  as  scanned  aerial  photogr^diy  or 
.  SPOT  satellitE  data 


image  rectification 

i.points  image  registralion  (assign  control  points) 

i.iectify  image  rectification 

i.taiget  establish  target  dat^ase  for  the  groiqp 

image  classification 

i.cluster  unsiqrervised  clusterii^g 

i.maQdik  maximum  likelihood  dasher 

otiier 

i.groijp  group  management 


8^  I^rogranimmg  IntorfiEKfi  for  Grotqs 

The  programming  interface  to  the  group  data  is  described  in  §24  Imagery  librcay 
Ip.  157]  and  the  reader  is  referred  to  that  chapter  for  details. 
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Chapter  9 

Wmdflw  and  Mask 


GRASS  users  are  provided  with  two  mechanisms  for  specifying  the  area  of  tiie  earth  in 
which  to  view  and  analyze  their  data  These  are  known  in  GRASS  as  the  window  and 
the  mask.  The  user  is  allowed  to  set  a  window  which  defines  a  rectangular  area  of 
coverage  on  the  earth,  and  optionally  furdier  limit  the  coverage  by  specifying  a 
"cookie-cutter"  mask.  The  window  and  mask  are  stored  in  the  database  under  the 
usei^s  current  ma^rset  GRASS  programs  automatically  retrieve  only  data  that  fall 
within  the  window.  Rirthermore,  if  there  is  a  mask,  only  data  that  fall  within  fire 
mask  are  retained.  Rngrams  determine  die  window  and  mask  from  the  database  rather 
than  asking  the  user. 


9.1.  Windoiv^ 

The  user's  current  database  window^  is  set  by  the  user  using  the  GRASS  window, 
Guindow,  or  dwindow  commands.  It  is  stored  in  the  WIND  ffle  in  the  mapset  This 
file  not  only  specifies  the  geographic  boundaries  of  the  window  rectangle,  but  also  the 
window  resolution  which  implicitly  grids  the  window  into  rectangular  "cells"  of  equal 
size. 


Users  expect  map  layers  to  be  resampled  into  die  current  window,  lliis  implies  that 
map  layers  must  be  extended  with  no  data  for  portions  of  the  window  which  do  not 
cover  the  map  layer,  and  that  the  map  layer  data  be  resampled  to  the  window 
resolution  if  the  cell  file  resolution  is  differeiiL  Users  also  expect  new  map  layers  to 
be  created  with  exactiy  the  same  boundaries  and  resolution  as  the  current  window. 


’  The  choice  of  the  term  "window"  is  unfortunatB.  ft  is  used  in  other  contexts  as  well  (e.g., 
gTEphics  windows)  leading  to  much  user  confusioa  A  better  teim  would  have  been 
"coverage."  When  confusion  arises,  refer  to  this  window  as  the  "database  window"  or  the 
"mapeet  window",  and  to  windows  on  the  graphics  screen  as  "graphics  windows." 
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ITie  WIND  file  contains  the  following  fields: 


WIND 


north: 

4660000.00 

south: 

4670000.00 

east: 

770000.00 

west: 

710000.00 

e-w  resol: 

50.00 

n-s  resol: 

100.00 

proj: 

1 

zone: 

18 

north,  south,  east,  west 

The  geographic  boundaries  of  the  window  are  given  by  the  north,  south,  east, 
and  west  fields.  Note:  these  values  describe  the  lines  which  bound  the  window  at 
its  edges.  These  lines  do  NOT  pass  through  the  center  of  the  grid  cells  which 
form  the  window  edge,  but  rather  alorig  the  edge  of  the  window  itself. 

e-w  resol,  n-s  resol 

Ihe  fields  e-w  resol  and  h-s  resol  (which  stand  for  east-west  resolution  and 
north-south  resolution  respectively)  describe  the  size  of  each  grid  cell  in  the 
window  in  physical  measurement  units  (e.g.,  meters  in  a  UTM  database).  The  e- 
w  resol  is  the  lerigtti  of  a  grid  cell  fiam  east  to  west  The  n-s  resol  is  fire  lengtii 
of  a  grid  cell  from  north  to  south.  Note  that  since  the  e-w  resol  may  differ  from 
the  n-s  resol,  window  grid  cells  need  not  be  square. 

proj,  zone 

The  pno/ection  field  specifies  die  type  of  cartographic  projectioir  0  is 
unreferenced  x,y  (imagery  data),  1  is  UTM,  2  is  State  Hane.^  Others  may  be 
added  in  the  firihrre.  The  zone  field  is  the  projection  zone.  In  the  example  above, 
the  projection  is  UIM,  the  zone  18. 

Note.  The  WIND  file  format  is  very  similar  to  the  format  for  the  cell  header 
files.  See  §5.5  Cell  Header  Fomxit  [p.26]  for  details  about  cell  header  files. 


9^  Mask 

In  addition  to  the  window,  the  user  may  set  a  mask  using  the  mask  command.  The 
mask  is  stored  in  the  user' s  current  mapset  as  a  cell  file  with  the  name  MASK^  The 
mask  acts  like  an  opaque  filter  when  reading  other  cell  files.  No-data  cells  in  the  ma^ 
(i.e.,  cat^ory  zero)  v\dll  cause  corresponding  cells  in  other  cell  files  to  be  read  as  no 
data  (irreqDective  of  the  actual  value  in  the  cell  file). 

2  State  Rane  is  not  yet  fully  supported  in  CHASS. 

The  rmsk  program  creates  MASK  as  a  leclass  file  because  the  reclass  function  is  fast  and 
uses  less  disk  space,  but  it  doeai’ t  actually  matter  that  MASK  is  a  reclass  file.  Any  cell  format 
can  be  used.  The  only  thing  that  really  matters  is  that  tlie  cell  file  be  called  MASK 
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The  foUowuig  dk(gFem  gives  a  visual  idea  of  how  Ihe  woiics: 


output 


0 

4 

4 

3 

3 

0 

2 

0 

0 

9.3.  Variations 

If  a  GRASS  program  does  not  obey  either  the  idndow  or  the  mask,  die  variation  must 
be  noted  in  the  user  documentation  for  the  program,  and  die  reason  for  die  variation 
given.  For  exan^le,  the  slope. aspect  program  which  generates  aspect  and  slope  maps 
from  elevation  data  uses  die  resolution  of  the  elevation  data  itself,  and  not  the  current 
window  resolution  (which  may  differ).  The  program  documentation  for  slope.aspect 
warns  die  user  about  this:  The  current  uindow  and  mask  settings  are  ignored.  The 
elevation  file  is  read  directly  to  insure  that  data  is  not  lost  or  inappropriately 
resampled. 
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Cfaapler  10 

Ekivirasnent  Variables 


GRASS  piDgrams  are  written  to  be  independent  of  which  database  die  user  is  using, 
where  the  database  resides  on  the  disk,  or  where  the  programs  thanselves  leside. 
When  programs  need  this  infonnation,  they  get  some  of  it  from  UNIX  environment 
vahables,  and  the  rest  from  GRASS  environment  variables. 


10.1.  UNIX  Emironmefit 

The  GRASS  stait-iq)  commands  GBASSS  and  grassS  set  the  following  UNIX 
environment  vahables:  ^ 


dSBASE  top  level  duectoiy  for  the  GRASS  programs 
GIS_LOCK  process  id  of  the  start-np  shell  script 
GISRC  name  of  the  GRASS  enviroment  ffle 


GISBASE  is  die  top  level  duectoiy  for  die  GRASS  programs.  For  examine,  if 
GRASS  were  installed  under  /grass,  thai  GISBASE  would  be  set  to  /grass.  The 
command  directory  would  be  /grassAxn,  the  command  siqrport  directory  would  be 
/grass/etc,  the  source  code  directory  would  be  /grass/^,  the  or>line  manual  would 
live  in  /grassAmn,  the  menu  files  would  be  found  in  /grassAnenu,  etc. 

GISBASE,  wWe  set  in  the  UNIX  environment,  is  given  giecial  handling  in  GRASS 
code.  This  variable  must  be  accessed  using  die  GIS  Library  routine  G^gisbase(p.66). 

GISJLOCK  is  used  for  various  locking  mechanians  in  GRASS.  It  is  set  to  the 
process  id  of  the  start-up  shell  so  that  lockii^g  mecharisms  can  detect  orphaned  locks 
(e.g.,  lodes  that  were  left  behind  during  a  system  crash). 

GIS_L(XK  mEty  be  accessed  using  the  UNIX  getenv( )  routine. 

GISEIC  is  set  to  the  name  of  die  GRASS  environment  file  where  all  other  GRASS 


’  Any  interface  to  GRASS  must  aet  these  variables. 
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vaiiables  are  stored.  Under  GRASS  3.0  this  file  is  jgrBaarc^  in  the  user's  home 
directory. 


10^  GRASS  Environment 

All  GRASS  users  will  have  a  file  in  their  home  directory  named  .grassrc^  which  is 
used  to  store  the  variables  that  comprise  the  environment  of  all  GRASS  programs. 
This  file  will  always  include  the  foUowirig  variadbles  that  define  the  database  in  which 
the  irser  is  working: 

OSDBASE  tup  level  database  directoiy 

IjC)CATION_NAME  location  directoiy 
MAPSET  mapeet  directoiy 


The  user  sets  these  variables  during  GRASS  start-tq).  While  the  value  of  GISDBASE 
will  be  relatively  constant,  the  others  may  change  each  time  the  user  runs  GRASS. 
GRASS  programs  access  these  variables  using  the  G.£isdbase{p.67),  GJocation(p.66), 
and  G _jTripset{p.  66)  routines  in  the  GIS  Library.  See  §4.2  Gisdbase  [p.  16]  for  details 
about  GIl^BASE,  §4.5  Locations  \p.  16]  for  details  about  database  locations,  and  §4.4 
Mapsets  (p.  16]  for  details  about  mapsets. 

Other  variables  may  appear  in  this  file.  Some  of  these  are: 

MONITOR  currently  selected  graphics  monitor 
PAINTER  currently  selected  paint  output  device 
DIGITIZER  currently  selected  digitizer 


These  variables  are  accessed  and  set  from  C  programs  using  the  general  purpose 
routines  G_geteTw(p.67)  and  G_setenv(p.67).  The  GRASS  program  gisenp  provides  a 
command  level  interface  to  these  variables. 


10,3.  Difference  BetvReen  GRASS  and  UNIX  Environments 

The  GRASS  environment  is  similar  to  die  UNIX  environment  in  diat  programs  can 
access  information  stored  in  "environment"  variables.  However,  since  the  GRASS 
environment  variables  are  stored  in  a  disk  file,  it  ofiFeis  two  cspabilities  not  available 

^  Under  previous  veraons  of  GRASS  this  fie  was  named  .giarc 

*  GRASS  programs  do  not  have  this  file  name  built  into  them  They  look  it  up  from  the 
UNIX  environmeiA  veriable  GISRC.  Note  tJie  sinilarify  in  naming  convention  to  the  .cshrc 
and  .exTC  files. 
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with  U^QX  environment  variables.  Rist;  variables  way  be  set  by  one  i»ngram  for 
later  use  by  otiier  programs.  For  esarople,  the  GRASS  start-ig)  sets  these  variables  for 
use  by  all  other  GRASS  application  progrEBus.  Second,  since  the  variables  romain  in 
the  file  unless  explicifiy  removed,  they  are  available  from  session  to  session. 
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Chapter  11 

Ccmpflmg  GRASS  I^ograms  Usiiiig  Gmake 


GRASS  programs  are  compiled  usipg  the  Gmake  front-end  to  the  UNIX  make 
command.  Gmake  reads  a  file  named  Gimkefile  to  construct  a  makefile  and  then  runs 
make.  (It  is  assumed  that  the  programmer  is  familiar  with  make  and  its  accompatiying 
makefiles.) 


11.1.  Gmake 

The  GRASS  Gmake  utility  allows  make  corrpilation  rules  to  be  developed  without 
handng  to  specify  machine-  and  installatiorr-dependent  information.  Gmake  combines 
pre-defined  variables  that  specify  the  machine-  and  installation-d^ndent  information 
with  the  file  Gmakefile,  which  the  programmer  must  write,  to  create  a  makefile.  (The 
pre-defined  variables  and  the  construction  of  a  Gmakefile  are  described  below.) 

Gmake  is  irrvoked  as  follows:^ 

Gmake  [soince  directoiy]  [taiget] 

If  run  without  arguments,  Gmake  will  run  in  the  current  directory,  build  a  makefile 
from  the  Gmakefile  found  there,  and  then  run  make.  If  run  with  a  source  directory 
argument,  Gmake  will  change  into  tfis  directory  and  then  proceed  as  above.  If  run 
with  a  target  argument  as  well,  then  make  will  be  run  on  the  q)ecified  target 


11.2.  Gmake  Variables 

The  pre-defined  Gmake  variables  which  the  GRASS  programmer  must  use  when 
writing  a  Gmakefile  specify  libraries,  source  and  binary  directories,  compiler  and 
loader  Bags,  etc.  The  most  commonly  used  variables  will  be  defined  here.  Exanples 
of  how  to  use  them  follow  in  §11.3  Comtructing  a  Gmakefile  [p.5S].  The  full  set  of 
variables  can  be  seen  m  Appendix  A  Annotated  Gmake  Pre-defined  Variables  \p.233]. 

*  Grruke  lives  under  $GISBASE^ae/CMD.  You  must  either  set  your  SPATH  to  include  this 
directoiy,  or  run  SGISBASEyarc/CMD/GnnkB.  (GISBASE  is  the  directoiy  whae  GRASS  is 
installed.  See  §10.1  UMX  Emironment  \p.  5i\  for  details. 
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Variables  marked  with  (-)  are  not  commonly  used. 

GRASS  Directarie&  The  following  variables  tell  Gmahe  where  source  code  and 

program  directories  are: 

GIS  (-)  This  is  the  UNIX  directory  where  GRASS  is  installed.  It  corresponds  to 
the  GRASS  environment  variable  GISBASE  (see  §iO  Enviromnent 
Variatdes  |p.5i]).  This  variable  is  generally  not  used  explicitly  in  a 
Gmakefile.  It  is  mosdy  used  by  Gmahe  to  construct  other  variables. 

SRC  (-)  This  is  the  directory  where  GRASS  source  code  lives. 

BIN  This  is  the  directory  where  user-accessible  GRASS  programs  live. 

EJTC  This  is  the  directory  where  support  files  and  programs  live.  These  sipport 

files  and  programs  are  used  by  the  $(BIN)  programs,  arxl  are  not  known 
to,  or  run  by  the  user. 

LEBDER  (-)  This  is  the  directory  where  most  of  the  GRASS  libraries  and  include 
header  files  live.  For  example,  "gis.h"  can  be  found  here.  Gmahe 
automatically  specifies  this  directory  to  the  C  compiler  as  a  place  to  find 
include  files. 

GRASS  Iilx«ie&  The  following  variables  name  the  various  GRASS  libraries: 

GESLIB  This  names  the  GIS  Library,  which  is  the  principal  GRASS  library.  See 
§22  GIS  Library  \p.  63]  for  details  about  this  library,  and  ^12.18  Loadwg 
the  GIS  Library  [p.  122]  for  a  sample  GmahefUe  which  loads  tfiis  library. 

VASKLiIB  This  names  the  Vask  Library,  which  does  full  screen  user  input 

VASK  This  specifies  the  Vask  Library  plus  the  UNIX  curses  arri  tennc^ 
libraries  needed  to  use  the  Vask  Library  routines.  See  §20  Vask  Library 
\p.  187]  for  details  about  this  library,  and  §20.4  Loading  the  Vask  Library 
\p.  191]  for  a  sample  GmahefUe  which  loads  this  library. 

SEGMENTLIB 

This  names  the  Segment  library,  which  manages  large  matrix  data  See 
§29  Segment  Library  \p.l79]  for  details  about  this  Ebrary,  and  §20.4 
Loading  the  Vask  Library  \p.  191]  for  a  sample  GmahefUe  which  loads  this 
library. 


RASTERLIB 

This  names  the  Raster  Graphics  Library,  which  communicates  with 
GRASS  graphics  drivers.  See  §25  Raster  Grofyhics  library  [p.l47\  for 
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details  about  this  libiaiy,  and  §i5.d  Loading  the  Haster  Graphics  library 
\p.  157]  for  a  sacople  Gmahefile  ^ch  bads  this  libiaiy. 

DISPLAYLIB 

This  names  die  Display  Graphics  library,  which  provides  a  higher  level 
graphics  interface  to  $(RASTEEILIB).  See  §16  Di^lay  Graphics  Library 
\p.l59\  for  details  about  this  libiaiy,  and  §16.9  Loading  the  Display 
Graphics  Library  Ip.  IGT]  for  a  sampb  Gmahefile  which  loads  this  libiaiy. 

UNIX  libraries.  The  following  vaiiables  name  some  useful  UNIX  system  libraries; 

MATHT.tr  This  names  the  madi  libiaiy.  It  should  be  used  instead  of  the  -bn  loader 
option 

CURSES  This  names  both  the  cmses  and  termcap  bbraries.  It  should  be  used  instead 
of  the  -Icurses  and  -Itermcap  loader  options.  Don’t  use  $(CURSES)  if  you 
use  $(VASO. 

TERMLIB  This  names  the  termcap  libiaiy.  It  should  be  used  instead  of  die  -Itenncap 
or  -Iteimlib  loader  options.  Dori  t  use  Sd’ERMLIB)  if  you  use  $(  VASK) 
or  $(CURSES). 

Corapikr  and  loado*  vanafaks.  The  foUoiving  variables  are  related  to  compiling  and 

loading  C  programs: 

AR  This  variable  specifies  the  rule  that  must  be  used  to  build  object  libraries. 

CFLAGS(-) 

This  variable  specifies  all  the  C  compiler  options.  It  should  never  be 
necessaiy  to  use  this  variable.  Gmahe  automatically  siqipUes  this  variable 
to  die  C  conpiler. 

EXTRA^CFLAGS 

This  variable  can  be  used  to  add  additional  options  to  $(CFLAGS).  It  has 
no  pre-defined  values.  It  is  usually  used  to  specify  additional  -I  include 
directories,  or  -D  pre-processor  defines. 

GMAKE  This  is  the  full  name  of  the  Grrahe  command.  It  can  be  used  to  drive 
compilation  in  subdirectories. 

LDFIAGS  This  specifies  the  loader  flags.  The  programmer  must  use  this  variable 
when  loading  GRASS  programs  since  there  is  no  way  to  automatically 
sipply  these  flags  to  the  loader. 
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MAKEALL 

This  defines  a  command  vdich  runs  Grmke  in  all  siixfiiectories  that  have 
^.GmahefUe  in  them 


11^.  Oiistructiiig  a  GmakE^ 

A  GimkefUe  is  constructed  like  a  makefile.  The  complete  syrtax  for  a  makefile  is 
discussed  in  the  UNIX  documentation  for  make  and  won’t  be  repeated  here.  The 
essential  idea  is  that  a  taiget  (e.g.,  a  GRASS  program)  is  to  be  birilt  finm  a  list  of 
dependencies  (e.g.,  object  files,  libraries,  etc.).  The  relationship  between  die  target  its 
dependencies,  and  the  rules  for  constructing  the  target  is  expressed  according  to  the 
following  syntax: 

target:  depedencies 
actions 
more  actions 

If  the  target  doesn’t  exist,  or  if  any  of  the  dependencies  have  a  newer  date  dian  the 
target  (i.e.,  have  changed),  the  actions  ivill  be  executed  to  build  the  target 

The  actions  must  be  indented  usirig  a  TAB.  Make  is  piclq^  about  this.  It  doesn’ t  like 
spaces  in  place  of  the  TAB. 


ll.ai.  Building  progiraiis  fiioni  source  (.c)  fifes 

To  build  a  program  from  C  source  code  files,  it  is  only  necessary  to  specify  the 
compiled  object  (.o)  files  as  dependencies  for  the  target  program,  and  then  specify  an 
action  to  lo^  the  object  files  together  to  form  the  program  The  rmke  utility  builds  .o 
files  from  .c  files  witout  being  instructed  to  do  so. 

For  example,  the  following  Gmakefile  builds  the  program  otyz  and  puls  it  in  the 
GRASS  program  directory. 


OBJ  ^  maiao  sci)l.o  sdb2.o  sii)3.o 

$(BIN)/xyz:  $(OBJ)  $(GESLIB) 

$(CO  $(LDFLAGS)  -o  $@  $(OBJ)  $(GISLIB) 

$(GI5LiIB):  *  in  case  libraiy  changes _ 


The  target  xyz  depends  on  the  object  files  listed  in  the  vaii£ble  $(OBJ)  and  the 
$(GISLEB)  library.  The  action  runs  the  C  con^iler  to  load  xyz  from  the  $(OBJ)  files 
and  $(GISLIB). 

$@  is  a  make  shorthand  which  stands  for  the  target,  in  this  case  xyz.  Its  use  should  be 
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encouraged,  since  the  taotget  name  can  be  changed  without  havmg  to  edit  the  action  as 
well. 

$(CC)  is  the  C  compila*.  It  is  used  as  the  inteiface  to  the  load^.  It  should  be  ^)ecified 
as  $(CC)  instead  of  cc.  Make  defines  $(CC)  as  cc,  but  using  $(CC)  will  allow  other 
C-like  conpilers  to  be  used  instead.^ 

$(BIN)  is  a  Gmake  variable  which  names  the  UNIX  directory  where  GRASS 
commands  live.  %)ecifyirig  the  target  as  $(BIN)/3£yz  will  cause  Grnake  to  build  ocyz 
directly  into  the  $(BIN)  directory. 

$(  LDFLAGS)  specify  loader  flags  which  must  be  passed  to  the  loader  in  this  manner. 

$(GISLIB)  is  the  GIS  Library.  $(GISIJB)  is  specified  on  the  action  line  so  that  it  is 
included  during  the  load  step.  It  is  also  specified  in  the  dependency  list  so  that 
changes  in  $(GISLIB)  will  also  cause  the  program  to  be  reloaded. 

Note  that  no  rules  were  given  for  building  the  .0  files  from  their  related  .c  files.  In 
fact  the  GRASS  programmer  should  almost  never  have  to  give  an  explicit  rule  for 
compiling  .c  files.  It  is  sufficient  to  list  all  the  .0  files  as  dependencies  of  the  target 
The  .c  files  will  be  automadcaUy  compiled  to  build  iq>-to-date  .0  files  before  the  .0 
files  are  loaded  to  build  the  target  program 

Also  note  that  since  $(GISLIB)  is  specified  as  a  dependency  it  must  also  be  specified 
as  a  target  Make  must  be  told  how  to  btdld  all  dependencies  as  well  as  targets.  In  this 
case  a  dummy  rule  is  given  to  satisfy  make. 


11.3.2.  Indude  files 

Often  C  code  uses  die  #  include  directive  to  include  header  files  in  die  source  during 
compilation  Header  files  that  are  included  into  C  source  code  should  be  specified  as 
dependencies  as  well.  It  is  the  .0  files  which  depend  on  them: 

I  OBJ  =  rnaiao  subl.o  sii)2.o  j 

$(BIN)/xyz:  $(OBJ)  $(G1]SLIB)  | 

$(CC)  $(LDFLAGS)  -o  $@  $(OBJ)  $(GISLIB)  j 

$(OBJ);  myheader.h 

$<GISLIB):  *  in  case  library  changes _ | 


-  GRf\SS  Grrake files  pieaentJy  use  cr  instead  of  $(CC).  This  will  be  modified  in  future 
release.^. 
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In  this  case,  it  is  assumed  det  "myheader.h"  lives  in  die  cuiient  directoiy  and  is 
included  in  each  source  code  file.  If  "myheader.h"  chartges,  then  all  .c  files  will  be 
compiled  ev^  though  they  may  not  have  chai^ged.  And  th^  the  target  program  ocyz 
will  be  reloaded. 

If  the  header  file  "rnyheaderh"  is  in  a  dififererii  .iiiectory,  then  a  different  formulation 
can  be  used: 


EXTRA^CHAGS  =  -I. 

OBJ  =  maao  subl.o  sii)2.o 

$(BIN)/)o^:  $(OBJ)  $((3SLIB) 

$(CO  $(LDFIAGS)  -o  $@  $(OBJ)  $(GISLIB) 

$(GISLIB):  *  in  case  library  changes _ 


$(EXTRA_CFLAGS)  will  add  die  flag  -L.  to  the  rules  tiiat  compile  .c  files  into  .0  files. 
This  flag  indicates  that  ^include  files  (i.e.,  "myheader.h")  can  also  be  found  in  the 
parent (..)  directory. 

Note  that  this  example  does  not  specify  that  "myheader.h"  is  a  dependency.  If 
"myheader.h"  were  to  charige,  this  would  not  cause  recompilation  here.  The  following 
rule  could  be  added: 

$(OBJ):  ../myheader.h 


11.3.3.  Bulling  object  libraries 

Sometimes  it  is  desirable  to  build  libraries  of  subroutines  which  can  be  used  in  many 
programs.  Grmke  requires  that  these  libraries  be  built  using  the  $(AR)  rule  as  follows: 


OBJ  =  subl.o  sdb2.o  subS.o 

lib.a  $(OBJ) 

_ $(AR) 


All  the  object  files  listed  in  $(OBJ)  will  be  compiled  and  archived  into  the  target 
library  lib.a.  The  $(OBJ)  variable  must  be  used.  The  $(AR)  assumes  that  all  object 
files  arc  li-^ted  in  $(OBrJ). 
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11.3.4  Buikfinifinixc  than  one  taifSe^ 

Many  target :  dependency  lines  many  be  given.  However,  it  is  the  first  one  in  the 
Gwakefile  which  is  built  by  Gwahe.  If  thoe  are  more  targets  to  be  built  the  first 
target  must  explicify  or  implicitly  cause  Gmahe  to  build  the  others. 

The  following  builds  two  programs,  abc  and  xyz  directly  into  the  ${BIN)  directory: 


ABC  =  abc.o  subl.o  8db2.o 
XYZ  =  xyz.o  subl.o  sdb3.o 

all;  $(BIN)/abc  $(BE^/xyz 

$(BE^)/abc:  $(ABC)  $(GKLIB) 

$(CC)  $(LDELAGS)  -o  $@  $(ABC)  $(GISLIB) 

$(BIN)/3^:  $(XYZ)  $(GISLIB) 

$(CC)  $(LDFLAGS)  -o  $@  $(ABC)  $(GISLIB) 

SlGISLEB):  *  in  case  libraiy  changes _ 


If  it  is  desired  to  run  the  compilation  in  various  subdirectories,  a  Gmahefile  could  be 
constructed  which  simply  runs  Gmnke  in  each  subdirectory.  For  example; 


$(GMAKED  sdbdir.l 
$(GMAKE)  subdir.2 
$(GMAKE)  subdir.3 


Note  that  due  to  the  the  $(AR)  rule  is  designed,  it  is  not  possible  to  construct 
more  than  one  libraiy  in  a  single  source  code  directory.  Each  library  must  have  its 
own  directory  and  related  Gmahefile. 


11.3.5.  Don^t  bypass  .offles 

If  a  program  has  only  one  .c  .source  file,  it  is  tenpting  to  corrpile  the  program  direcdy 
i'rom  the  .c  file  v/ithout  creating  the  .o  file.  Hease  don’t  do  this.  There  have  been 
pn)bleni.s  on  some  systems  specifying  both  corrpiler  and  loader  flags  at  the  same  time. 
'I'he  .0  files  must  be  built  first  Once  all  the  .o  files  are  built  they  are  loaded  with  any 
nx^uired  libraries  to  build  the  prognun. 
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Chapter  12 
GIS  Library 


12.1.  Introduction 

The  GIS  Library  is  the  primary  piDgrannnmg  library  provided  with  the  GRASS 
system  RvgraoiB  must  use  this  libary  to  access  tiie  database.  It  contaiiis  the 
routines  which  locate,  create,  open,  rename,  and  remove  GRASS  database  files.  It 
contains  the  routines  which  read  and  write  cell  files.  It  contains  routines  which 
interface  the  user  to  the  database,  including  proirpting  the  user,  listing  available  files, 
validating  user  access,  etc.  It  also  has  some  general  propose  routines  (string 
manipulation,  user  information,  etc.)  which  are  not  tied  directly  to  database  processii^. 

It  is  assumed  that  the  reader  has  read  §4  Database  Sructure  [p.15]  for  a  general 
description  of  GRASS  databases,  §5  Grid  Cell  Maps  [p.23]  for  details  about  map  layers 
in  GRASS,  and  §9  Window  and  Mask  Ip.  47]  which  discusses  windowirig  and  masking. 

The  routines  in  the  GIS  Library  are  presented  in  functional  groiqpir^,  rather  than  in 
alphafoetical  order.  The  order  of  presentation  will,  it  is  hoped,  provide  a  better 
understanding  of  how  the  library  is  to  be  used,  as  well  as  show  the  inter-relationships 
among  the  various  routines.  Note  that  a  good  way  to  understand  how  to  use  these 
routines  is  to  look  at  tire  source  code  for  GRA^  programs  which  use  them 

Most  routines  in  this  library  require  that  the  header  file  "gis.h"  be  included  in  arty  code 
using  these  routines.^  Therefore,  programmers  should  always  include  this  file  when 
writing  code  using  routines  from  this  library: 

#  include  "gis.h" 

Note.  All  routines  and  global  variables  in  this  library,  documented  or  undocumented 
.start  with  the  prefix  G_.  To  avoid  name  conflicts,  programmers  should  not  create 
variables  or  routines  in  their  own  programs  which  use  this  prefix. 

An  alphabetic  index  is  provided  in  ^24.5  Appendix  C.  Index  to  GIS  library  \p.239\. 


’  The  GRASS  compilation  process,  described  in  §i2  Corrpilirig  GRASS  Bograryis  Using 
Gmake  \r  xii,  automatically  tells  the  C  conpiler  how  to  find  this  and  other  GRASS  header  files. 
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litarary  Initializaticn 

It  is  mendatoy  that  the  system  be  initialized  bdbie  ai^  other  libraiy  routines  are 
called. 

G  gisirit  (progranL-name)  imtialuB  gis  library 

char  *programjiame; 

This  routine  reads  the  usei's  GRASS  environment  file  into  memory  and  makes 
sure  that  the  iser  has  selected  a  valid  database  and  mapset  It  also  initializes 
hidden  variables  used  by  other  routines.  If  the  user's  database  information  is 
invalid,  an  error  message  is  printed  and  die  program  exits.  The  progranmame 
is  stored  for  later  recall  by  G_progtxmijmrTe(p.ll8).  It  is  recommended  that 
argv[0]  be  veed  for  the  progranoianie: 

maintargc,  argv)  char  *aigv(  ]; 

{ 

G_giMt(aigv[0] ) ; 

} 


12,3.  ENagDostic  Messages 

Tte  foUowirig  routines  are  used  by  other  routines  in  the  libraay  to  report  warning  and 
error  messages.  They  may  also  be  used  directiy  by  GRASS  programs. 

G  fafed  frmr  (message)  print  error  message  and  exit 

G_waming  (message)  print  warning  message  and  continue 

char  *message; 

These  routines  report  errors  to  the  user.  The  normal  mode  is  to  write  the 
message  to  the  screen  (on  the  standard  error  output)  and  wait  a  few  seconds. 
G_wamirTg( )  will  return  and  G_fataLerror< )  will  exit 

If  the  starxlard  error  output  is  not  a  tly  device,  then  the  message  is  mailed  to  the 
user  instead. 

If  the  file  GIS_ERROR_LOG  exists  (with  write  permission),  in  either  the  usei^  s 
home  directory  or  in  the  $GISBASE^  directory,  the  messages  will  also  be  logged 
to  this  file. 

While  most  applications  will  find  the  normal  error  reporting  quite  adequate,  there  will 
be  times  when  different  handling  is  needed.  For  example,  graphics  programs  may 

SGISBASE  is  the  directory  where  GRASS  is  installed.  See  §20.2  UNIX  Environment 
fp  .T/ 1  for  details. 
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want  the  messages  di^layed  graphically  instead  of  on  the  standard  enor  ou4)ut  If  the 
programmer  wants  to  handle  the  error  messages  differendy,  the  following  routines  can 
be  used  to  modify  the  error  handling*- 

Gjset_€nXir_routilie  (handler)  change  error  handing 

int  (*handler)( ); 

This  routine  provides  a  different  error  handler  for  Gjfatal_ern)d )  and 
G_waming( ).  TTie  handla*  routine  must  be  defined  as  follows: 


handler  (message,  fatal) 
char  *inessage; 
int  fatal; 


where  measE^  is  the  message  to  be  handled  and  fatal  indicates  the  type  of  error  : 
1  (fatal  error)  or  0  (warning). 

Note.  The  handler  only  provides  a  way  to  send  the  message  somewhere  other 
than  to  the  error  outyiut  If  the  error  is  fatal,  the  program  will  exit  after  the 
handler  returns. 

G_un8et_emr_Jt)Wtin^  ( )  reset  normal  error  handling 

This  routine  resets  the  error  handlirig  for  GJatal_error{p.  64)  and  G_warmng(p.  64) 
back  to  the  default  actioa 

Gjleq)_an_error  (flag)  sleep  on  envr? 

int  flag; 

If  is  0,  then  no  pause  will  occur  after  printing  an  error  or  warning  message. 
Otherwise  the  pause  will  occur. 

G_suppres8_wamil^  ( flag)  suppress  uxanings? 

int  flag; 

If  flag  is  0,  then  G_iuaming(p.  64)  will  no  loiiger  print  warning  messages.  If  ^ag 
is  1,  then  G_waming( )  will  print  warrii^  messages. 

Note.  This  routine  has  no  effect  on  GJutal_error{p.64). 
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12.4.  Enviromnent  and  Dtedabase 

The  following  routines  return  information  about  tiie  cunent  database  sdected  by  the 
user.  Some  of  dns  information  is  retrieved  horn  the  user's  GRASS  enviroranent  file. 
Some  of  it  comes  from  files  in  the  database  itself.  See  §iO  Ekuironment  Vcaiables 
{p.  51]  for  a  discussion  of  the  GRASS  environment 

The  following  four  routines  can  be  used  freely  by  the  progrEimmer: 
char* 

Gjjocation  (  )  current  location  name 

Returns  the  name  of  the  current  database  location  This  routine  should  be  used 
by  progrEuns  that  need  to  display  the  current  location  to  the  user.  See  §4.3 
Locations  |p.  16]  for  an  explanation  of  locations. 

char* 

G_map9et  ( ) 

Returns  tiie  name  of  the  current  mapset  in  the  current 
often  used  when  accessing  files  in  ^  current  mapset 
for  an  explanation  of  ma^ts. 

char  * 

G_JtlQViame  ( )  location  title 

Returns  a  one  line  title  for  the  database  location  This  title  is  read  from  the  file 
MYNAME  in  tiie  PERMANENT  mapset  See  also  §4.3  Permanent  Mapset  \p.  19] 
for  a  discussion  of  the  PERMANENT  mapset 

char  * 

G_gNbase  (  )  top  level  program  directory 

Returns  the  full  path  name  of  tiie  top  level  directory  for  GRASS  programs.  This 
directory  will  have  subdirectories  which  will  contain  programs  and  files  required 
for  the  running  of  the  system  Some  of  these  directories  are: 

bin  connmands  run  by  the  user 

etc  programB  and  data  hies  used  by  GRASS  commands 

txt  help  hies 

menu  hies  used  by  the  gmssS  menu  interface 

The  use  of  G_gisbase( )  to  find  these  siixliiectories  enrbles  GRASS  programs  to 
be  written  independently  of  where  the  GRASS  ^stem  is  actually  installed  on  the 
machine.  For  example,  to  run  the  program  srvff  in  the  GRASS  etc  directory: 

char  command[200]; 

sprintf  (command,  "%8(etc/aroff’.  G_gidbaae( )  ); 
grstem  (command); 


current  mapset  name 

location  This  routine  is 
See  §4.4  Mapsets  Ip.  16] 
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The  following  two  routines  return  fiill  path  UNIX  directoiy  names.  Hiey  should  be 
used  only  in  special  cases.  They  are  used  by  other  routines  in  the  libraiy  to  build  full 
UNIX  file  names  for  database  files.  The  progranmer  should  not  use  the  negct  two 
roijdiiies  to  bypass  die  normd  database  access  routines. 

char* 

G_gisdbase  ( )  top  level  database  directory 

Returns  the  full  UNIX  path  name  of  the  directoiy  which  holds  the  database 
locations.  See  §4.2  Gisdbase  [p.  16]  for  a  full  explanation  of  tins  directoiy. 

char  * 

G_iocation^path  (  )  current  location  directory 

Returns  the  full  UNIX  path  name  of  the  cinrent  database  location.  For  example, 
if  the  user  is  woridng  in  location  spearftsh  in  the  Atsr/grass3/data  database 
directoiy,  this  routine  will  return  a  string  which  looks  like 
Atsr/grass3/datw^pecirfish. 

These  next  routines  provide  the  low-level  management  of  the  information  in  the  user' s 
GRASS  environment  file.  They  should  not  be  used  in  place  of  the  hazier  level 
intarfaoe  routines  described  above 

char  * 

G_getenv  (name) 
char  * 

G__gettiiv  (name) 
char  *name; 

The^e  routines  look  tp  the  variable  name  in  the  GRASS  environment  and  return 
its  value  (which  is  a  character  string). 

If  name  is  not  set,  G_getenv( )  issues  an  error  message  and  calls  exiti ). 
G_  setenv( )  just  returns  the  NULL  pointer. 

G_setenv  (name,  value)  set  GRASS emironment  vwiable 

G sete:  .v  (name,  value)  set  GRASS emvonment  variable 

char  *name; 
char  *value; 

These  routines  set  the  the  GRASS  environment  variable  name  to  value.  If  value 
is  NULL,  the  name  is  unset 

Both  routines  set  the  value  in  program  memory,  but  only  G_setenv( )  writes  the 
new  value  to  the  useri  s  GRASS  environment  file. 


query  CSRASS  emironment  variable 
query  (StAlS  environment  variable 
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12.5.  F^mifaniPiAal  Datahaae  Aooeas  Rnuttnes 

The  routines  described  in  this  section  {uovide  the  low-levd  interface  to  the  GRASS 
database,  search  the  database  for  files,  prompt  the  user  for  file  naoies,  open  files 
for  readily  or  writiiig,  etc.  Ihe  programmer  should  never  bypass  this  level  of  database 
interface.  These  raiitiiies  nrat  be  ised  to  aooess  the  GRA^  database  unleas  there 
are  odier  level  Ufaraiy  roirfines  ^nbich  perform  the  same  ifimcdan.  For 

example,  there  are  routines  to  process  cell  files  vdiich  should  be  used  instead  (see 
§i2.8  Cell  File  Processing  Ip.SO]). 

In  the  descriptions  below,  the  term  database  element  is  used.  Elements  are 
sibdirectories  within  a  nspset  and  are  associated  with  a  specific  GRASS  data  type. 
For  example,  cell  files  live  in  die  "cell"  element  See  §4.5.2  Elements  \p.  /S]  for  more 
details. 


12.5.1.  Prompting  for  Database  Files 

The  following  routines  interactively  prompt  the  user  for  a  file  name  from  a  specific 
HfltahasR  element  (See  §4.5.2  Elements  [p.i8]  for  an  explanation  of  elements.)  In 
each,  the  proiiyt  string  will  be  printed  as  die  first  line  of  die  full  prompt  which  asks 
the  user  to  enter  a  file  name.  If  prompt  is  the  empty  stiiqg  ""  dt^  an  appropriate 
prompt  wm  be  substituted.  The  name  that  the  user  enters  is  copied  into  the  name 
buffer.^  The  short  (one  or  two  word)  labd  describing  the  demerd  is  used  as  part  of  a 
tide  when  listing  the  files  in  ciement 

The  user  is  required  to  enter  a  valid  file  name,  or  else  hit  the  RETURN  key  to  cancel 
the  request  If  die  user  enters  an  invalid  re^nse,  a  message  is  printed,  and  the  user 
is  prompted  again.  If  the  user  cancels  the  request,  the  NULL  pointer  is  returned. 
Otherwise  the  mspset  where  the  file  lives  or  is  to  be  created  is  returned.  Both  the 
name  and  the  mapset  are  used  in  other  routines  to  refer  to  the  file. 

An  exanple  will  be  given  here.  The  G_ast.old( )  routine  used  in  the  example  is 
described  a  bit  later.  The  user  is  asked  to  enter  a  file  from  the  "paint/labels"  element: 

char  name[50]; 
char  ’^mapeet; 

nsipset  =  G_a6k_old  ( " name,  "paint/labds",  "labd^"); 
if  ( mapset  =  =  NULL) 

exitlO);  /*  user  canceled  the  request  */ 

The  user  will  see  the  following: 


The  size  of  name  should  be  larige  enough  to  hold  any  GRASS  file  name.  Most  systems 
allow  file  names  to  be  quite  long.  It  is  reconinended  that  name  be  declared  char  mire! 50], 
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Bnter  the  name  of  an  eadaling  labels  file 
filter  ’listf  for  a  list  of  existing  labels  files 
Ht  RETTURN  to  cacel  requesf^ 

> 


char  * 

G_ask_old  (prompt,  name,  element,  label)  pronpt  for  exisUng  database  file 

char  *prompt; 
char  *name; 
char  *element; 
char  *label; 

The  user  is  asked  to  enter  the  name  of  an  existing  database  file. 

Note.  This  routine  looks  for  the  file  in  the  current  mapset  as  well  as  other 
mapsets.  The  mapsets  that  are  searched  are  detemined  fiwm  the  user's  mapset 
search  path.  See  §4.7.1  Mapset  Search  Path  \p.20]  for  some  more  details  a^ut 
the  search  path. 

char  * 

G_askjiew  (prompt,  name,  element,  label)  prompt  for  new  database  file 

char  *prompt; 
char  *name; 
char  *element; 
char  *label; 

The  user  is  asked  to  enter  the  name  of  a  new  file  which  does  not  exist  in  the 
ciarent  mapset 

Note.  The  file  chosen  by  the  user  ma^^  exist  in  other  mapsets.  This  routine  does 
not  look  in  other  mapsets,  since  die  assumption  is  that  name  will  be  used  to 
create  a  new  file.  New  files  are  always  created  in  the  current  mapset 


'rhis  line  of  the  prompt  can  be  modified  using  G  _set.  ask_retion_mBg^p  To). 
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char  * 

O  arft;  ir^  mH|TBrt  (pronpt,  name,  element,  label)  pronpe  for  existing  database  file 

char  ^prompt; 
char  *name; 
char  *eleirient; 
char  *label; 

The  iiser  is  asked  to  enter  the  name  of  an  hie  which  exists  in  the  cmrmt  mapset 

Note:  The  hie  chosen  by  die  user  may  or  may  not  exist  in  other  mapsets.  This 
routine  does  not  look  in  other  mapsets,  since  the  assumption  is  that  name  will  be 
used  to  modify  a  hie.  GRAJSS  only  permitB  users  to  modify  hies  in  the  current 
mapset 


char  * 

G_ask_any  (prompt  name,  element  label,  warn)  prorrpt  for  valid  file  name 

char  *pit)mpt 
char  *name; 
char  ^element 
char  *label; 
int  warn; 

TTie  user  is  asked  to  enter  any  l^al  hie  name.  If  warn  is  1  and  the  hie  chosen 
exists  in  the  current  mapset  then  the  user  is  asked  if  it  is  ok  to  overwrite  the  hie. 
If  warn  is  0,  then  any  l^pal  name  is  accepted  and  no  warning  issued  to  the  user  if 
the  hie  exists. 

G_J9eCasluieturnjn8g  (msg)  set  Hit  REWRN  msg 

char  *m^, 

The  "Hit  RETURN  to  cancel  request"  part  of  the  prompt  in  the  pronopting 
routines  described  above,  is  modihed  to  "Ht  RETURN  nsg." 

char  * 

G_glEt-asluneturnjn8g  (  )  get  Ht  RB^WRN  msg 

The  current  msg  (as  set  by  G_set_ask_retumjvBg(p.  70))  is  returned. 


12.5,2.  Flntfing  Files  in  the  Database 

Non-interactive  programs  cannot  make  use  of  the  interactive  prompting  routines 
described  above.  For  example,  a  command  line  driven  program  may  reqirire  a  datsbase 
hie  name  as  one  of  the  command  arguments.  GRASS  allows  the  user  to  specify 
database  hie  names  either  as  a  simple  unqualihed  name,  such  as  "xyz",  or  as  a  fully 
qualihed  name,  such  as  "xyz  in  mapset".  where  mapset  is  the  mapset  where  the  hie  is 
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tD  be  found.  Often  only  the  unqualified  file  name  is  provided  on  the  command  line. 
The  following  routines  search  the  database  for  files: 


char  * 

G_fincLfle  (element,  name,  mapset) 
char  * 

G_6ndJi€2  (element,  name,  mapset) 

char  ^element; 
char  *name; 
char  *m^)set; 

Look  for  the  file  name  under  the  specified  dement  in  the  database.  The  mapset 
parameter  can  either  be  the  empty  string  which  means  search  all  the  m^)sets 
in  the  user' s  current  m£pset  search  path,^  or  it  can  be  a  specific  mapset,  which 
means  look  for  the  file  only  in  this  one  mapset  (for  example,  in  the  current 
mapset). 

If  found,  the  mapset  where  the  file  lives  is  returned.  If  not  found,  the  NULL 
pointer  is  returned. 

The  difference  between  these  two  routines  is  tiiat  if  tire  user  specifies  a  fully 
qualified  file  which  exists,  then  Gjfind_file2( )  noodifies  name  by  removing  the 
"in  mapset"  while  G_iindj51e< )  does  not®  Normally,  the  GRASS  programmer 
need  not  worry  about  qualified  vs.  unqualified  names  since  all  library  routines 
handle  both  forms.  However,  if  the  programmer  wants  the  name  to  be  returned 
unqualified  (for  displayirig  the  name  to  the  user,  or  storirig  it  in  a  data  file,  etc.), 
then  GjTncLfile2( )  should  be  used. 

For  example,  to  fiixl  a  "paint/labels"  file  antywheie  in  the  database: 

char  namef  501; 
char  ^rreqjaet; 


find  a  database  file 
finda  database  file 


if  Km^jset  =  G_fincLfile("paint/labeJs",name,""))  ==  NULL) 
/*  not  found  */ 

To  check  that  the  file  exists  in  the  current  mapset: 


^  See  §4.7 J  Mapset  Seaivh  Path  [p.20]  for  mote  details  about  the  search  path. 

^  Be  warned  that  G_find..fTle2( )  should  not  be  used  directly  on  a  command  line  ai^ument. 
ance  modifying  ai^gvl  |  may  not  be  valid.  The  argument  should  be  copied  to  another  character 
buffer  which  is  then  passed  to  G_fTncLfile2(  ) 
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char  taneCSO]; 

if  (G_find_fUe("paint/liWef',nenB,G_jn^^  ==  NULL) 
/"  not id*/ 


12.5w3.  File  Nediks 

Not  all  iiEimes  that  a  user  may  enter  will  be  legd  files  for  the  GRASS  databases.  The 
routines  which  create  new  files  require  that  the  new  file  have  a  legal  name.  The 
routines  which  prompt  the  user  for  file  names  (e.g.,  G_psk_neuip.69))  guarantee  that 
the  name  entered  by  the  user  wUl  be  legal.  If  the  name  is  obtained  hum  the  command 
line,  for  example,  the  programmer  must  check  that  die  name  is  l^al.  The  following 
routine  checks  for  legal  file  names: 

GJl€gaL01enanie  (name)  check  for  legal  database  fUe  names 

char  *name; 

Returns  1  if  name  is  ok,  -1  if  it  isn’ t 


12.5.4  OpennganEsistiiigDatEdbaaeFUefcr  ReadB^ 

The  following  routines  open  the  file  name  in  m^set  from  the  specified  database 
eiemeit  for  reading  (but  not  for  writing).  'Hie  file  name  and  mapset  can  be  obtained 
interactively  uang  G_ask_oldip.69),  and  non-interactively  using  GJwdJjleip.71)  or 
GJvndJile2{p.  71). 

G_open_oid  (element,  name,  mapset)  open  a  database  file  for  reading 

char  *element; 
char  *name; 
char  *mapset; 

The  database  file  name  under  the  dement  in  the  specified  mapset  is  opened  for 
reading  (but  not  for  writing). 

The  UNIX  open( )  routine  is  used  to  open  the  file.  If  the  file  doesn’ t  exist,  -1  is 
returned.  Otherwise  the  file  descriptor  from  the  open!  )  is  returned. 
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FILE  * 

Gjfoi)aL.cld  (demenl,  name,  mapeet)  open  a  database  /3c  for  reading 

char  *element; 
char  *name; 
char  *m£pset; 

The  database  hie  name  under  the  denmt  in  the  specified  meiiset  is  opened  for 
reading  (but  not  for  writing). 

The  UNIX  fopen( )  routine,  with  "r"  read  mode,  is  used  to  open  the  file.  If  the 
file  doesn’ t  exist,  the  NULL  pointer  is  returned.  Otherwise  the  file  descriptor  from 
the  fopen( )  is  returned. 


12.5^  Opening  an  Existing  DoEbaliase  File  for  l^jdate 

The  following  routines  open  the  file  name  in  the  cunent  m^)set  from  the  specified 
database  ekmoit  for  writing.  Ihe  file  must  exist  Its  name  can  be  obtained 
interactively  t^ing  G_askJ.ri_mapsetip.70),  and  non-interactively  usii^  GJmdJUeip.ll) 
or  G_findJUe2{p.  71). 

G_open^iq)da4e  (element,  name)  open  a  database  file  for  update 

char  *element; 
char  *name; 

The  database  file  name  under  the  dement  in  the  current  mapset  is  opened  for 
reading  and  writing. 

The  UNIX  open( )  routine  is  used  to  open  the  file.  If  the  file  doesn’ t  exist  -1  is 
returned.  Otherwise  the  file  is  positioned  at  the  end  of  the  file  and  the  file 
descriptor  from  the  open( )  is  returned. 

G_fopen_append  (element  name)  open  a  database  file  for  iqxhte 

char  *element; 
char  *name; 

The  database  file  name  under  the  demEnt  in  the  current  mapset  is  opened  for 
appending  (but  not  for  reading). 

The  UNIX  fopert  )  mutine,  with  "a"  append  mode,  is  used  to  open  the  file.  If'  the 
file  doesn’ t  exist  the  NULL  pointer  is  returned.  Otheiwise  the  file  is  positioned  at 
the  end  of  the  file  and  the  file  descriptor  from  the  fopent )  is  returned. 
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12.6.6.  Cicating  and  Openhig  a  Nm  DiBtalnse  Fite 

The  foUowii^  routines  create  the  new  tile  name  in  tiie  current  mapset^  under  tie 
specitied  Hafahasp  demEXit  and  open  it  for  writing.  Tie  database  dem^  is  created,  if 
it  ioesn’ t  already  exist 

Tie  tile  ngmr¥>  should  be  obtaiied  interactively  using  G_xisk_neuip.69).  If  obtained 
ren-interactively  (e.g.,  from  tie  command  line),  GJegalJUenameip.72)  should  be 
called  first  to  make  sure  that  name  is  a  valid  GRASS  tile  name. 

Waning.  It  is  ret  an  error  for  name  to  already  exist  However,  the  file  will  be 
reneved  ard  recreated  enpfy.  The  interactive  routiie  G_ask_neu(p.69)  guarantees 
that  name  will  not  exist  but  if  name  is  obtained  from  the  command  line,  name 
exist  In  tins  case  GJindJUeip.  71)  could  be  used  to  see  if  name  exists. 

G_<]|jen_new  ( element  name)  open  anew  database  file 

char  *element 
char  *name; 

The  file  name  urder  tire  element  in  the  current  mapset  is  created  and 

opened  for  writing  (but  not  reading). 

The  UNIX  open( )  routine  is  used  to  open  the  file.  If  the  file  doesn’ t  exist  -1  is 
returned.  OtiWwise  the  file  is  positioned  at  the  end  of  the  file  and  tiie  file 
descriptor  from  the  open( )  is  returned. 


FILE  * 

GjFopenjnew  (element  name)  open  a  new  database  file 

char  ^element 
char  *name; 

The  databsee  file  lEime  utder  the  element  in  the  current  mapset  is  created  and 
opened  for  writing  (but  not  reading). 

The  UNIX  fopen( )  routine,  with  "w"  write  mode,  is  used  to  open  the  file.  It'  the 
file  doesn’t  exist  the  NULL  pointer  is  returned.  Otherwise  the  file  is  positioned  at 
the  end  of  the  file  ard  the  file  descriptor  from  the  fopen( )  is  returned. 


^  GRASS  doeai’t  allow  files  to  be  created  outside  the  currert  mapset;  see  §4.7  Database 
Access  Rales  \p.  so]. 
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12.5.7.  Dolabwc  File  Managcmefit 

The  following  routines  allow  the  renaming  and  renaoval  of  database  files  in  the  current 
mapset® 

G_renailie  (element,  old,  new)  remrm  a  database  file 

char  *  element; 
char  *old; 
char  *new; 

The  file  or  director  <dd  under  the  database  dement  directory  in  the  current 
mapset  is  renamed  to  new. 

Returns  1  if  successful,  0  if  dd  doesn’ t  exist,  and  -1  if  there  was  an  error. 

Bug.  This  routine  doesn’ t  check  to  see  if  the  new  name  is  a  valid  database  file 
name. 

G_ren»ve  (element,  name)  rerwie  a  database  file 

char  ^element; 
char  *name; 

The  file  or  directory  name  under  the  datdrase  deniant  directory  in  the  current 
rricpset  is  removed. 

Returns  1  if  successful,  0  if  name  doesn’ t  exist,  and  -1  if  there  was  an  error. 

Note  If  name  is  a  directory,  everything  within  the  directory  is  removed  as  well. 


Note  These  functions  only  apply  to  the  specific  dement  and  not  to  other  "related" 
elements.  For  example,  if  dement  is  "cell",  then  the  specified  cell  file  wiU  be  remove 
'or  renamed),  but  the  other  stpport  files,  such  as  "celllxi"  or  "cats",  will  not  To 
remove  these  other  files  as  well,  specific  calls  must  be  made  for  each  related  dement. 


12.6.  Memory  Allocation 

The  following  routines  provide  memory  allocation  capability.  They  are  simply  calls  to 
the  UNIX  suite  of  memory  allocation  routines  mallod  ),  ixallocl  )  and  called  K  except 
that  if  there  is  not  enough  memory,  they  print  a  diagnosUc  message  to  that  effect  and 
then  call  exit( ). 

Note.  Use  the  UNIX  free( )  routine  to  release  memory  allocated  by  these  routines. 

^  Tbese  functions  only  apply  to  the  current  mapeet  ance  GR^\SS  does  permit  leers  to 
iirdify  things  in  mapse-ts  otlier  than  the  current  mapset;  see  §4.7  Datubase  Access  Rules  \p.2<i . 
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char  * 

G_JlldliOC  (size)  mwory  allocation 

intsize; 

Allocates  a  block  of  n^moiy  at  least  size  bytes  which  is  aligned  propeiiy  for  all 
data  types.  A  pointer  to  the  aligned  block  is  returned. 

char  * 

G_JieaIloc  (ptr,  size)  rremory  allocation 

char  *ptr, 
int  size; 

Changes  the  size  of  a  previously  allocated  block  of  memoiy  at  ptr  and  returns  a 
pointer  to  the  new  block  of  memoiy.  The  size  may  be  larger  or  smaller  than  tte 
original  size.  If  the  original  block  cannot  be  extended  "in  place",  then  a  new 
block  is  allocated  and  the  original  block  copied  to  the  new  block 

Note:  If  ptr  is  NULL,  then  this  routine  simply  allocates  a  block  of  aze  b3^s. 
This  is  different  than  maUocC ),  which  does  not  handle  a  NULL  ptr. 

char  * 

G_calloc  (n,  size)  rrenviy  allocation 

int  n; 
int  size; 

Allocates  a  properly  aligned  block  of  memory  msize  bytes  in  length,  initializes 
the  allocated  memory  to  zero,  and  returns  a  pointe.-  to  the  allocated  block  of 
memory. 

Note  Allocating  memory  for  reading  and  writing  cell  files  is  discussed  in  ^12.8.5 
Allocating  Cell  I/O  Buffers  (p.851 


12.7.  The  Window 

The  window  concept  is  explained  in  §9.i  Window  Ip.  47].  It  can  be  thought  of  as  a 
two-dinrensional  matrix  with  known  boundaries  and  rectangular  cells. 

There  are  logically  two  different  windows.  Tire  first  is  the  database  window  that  the 
user  has  set  in  the  current  mapset  The  other  is  the  window  that  is  active  in  the 
program.  This  active  program  window  is  what  controls  reading  arxl  writing  of  cell  file 
data. 

The  routines  described  below  use  a  GRASS  data  structure  CeUJiead  to  hold  window 
information  This  structure  is  defined  in  the  "gis.h"  header  file.  It  is  discussed  in 
detail  under  ^12.17  GIS  Library  Data  Structures  Ijo  118\. 
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12.7.1.  The  Database  Windovir 

Reading  and  writing  the  usei' s  database  window  are  done  by  the  following  routines: 

G_getLwindow  (window)  read  the  database  idndow 

struct  CelLjhead  ^window; 

Reads  the  database  window  as  stoned  in  the  WIND  file  in  the  useris  curnent 
mapset  into  window. 

An  error  message  is  printed  and  exit( )  is  called  if  there  is  a  problem  reading  the 
window. 

Note.  GRASS  applications  that  read  or  write  cell  files  should  not  use  this 
routine,  since  its  use  inches  that  the  active  program  window  will  not  be  used. 
FVograms  that  read  or  write  cell  file  data  (or  vector  data)  can  query  the  active 
program  window  usirig  Gjuindow_roiuBip.78)  and  G_umdow_coMp.78). 

G_put_  window  (window)  write  the  database  window 

struct  CelLhead  ^window; 

Writes  the  database  window  file  (WIND)  in  the  user's  current  mapset  from 

window. 

Returns  1  if  the  window  is  written  ok  Returns  -1  if  not  (no  diagnostic  message  is 
printed). 

Warning:  Sbice  this  routine  actually  changes  the  database  window,  it  should 
only  be  called  by  programs  which  the  user  knows  will  change  the  window.  It  is 
probably  fair  to  say  that  under  GRASS  3.0  only  the  window,  Guindow,  and 
d.window  programs  should  call  this  routine. 

There  is  another  database  window.  This  window  is  the  default  wirxlow  for  the 
location  The  default  window  provides  the  user  with  a  "starting"  window,  i.e.,  a 
window  to  begin  with  arxl  return  to  as  a  reference  point  The  GRASS  programs 
uindow  and  Guincbw  allow  the  user  to  set  their  database  window  from  the  default 
window.  (See  ^4.6  Permanent  Mapset  \p.  19]  for  a  discussion  of  the  default  window.) 
Tlie  following  routine  reads  this  window: 
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G_geL.de£BuULMiiidaw  (window)  nad  the  deftwlt  window 

struct  CJelLhead  *wii]dow; 

Reads  the  default  window  for  tbe  location  into  window. 

An  error  message  is  piinSed  and  exit( )  is  called  if  there  is  a  problem  reading  the 
default  window. 


12.7.2.  The  Active  I¥ogram  Window 

The  active  progreim  window  is  the  one  that  is  used  when  reading  and  writing  cell  file 
data  This  window  determines  the  resampling  when  reading  cell  data  It  also 
detemnines  the  extent  and  resolution  of  new  cell  files. 

Initially  the  active  program  window  and  the  usei^s  database  window  are  the  same,  but 
the  programmer  can  make  them  different  The  following  routines  manage  the  active 
program  window. 

G_window_rows  (  )  marber  of  rows  in  active  uindow 

G_window_cds  ( )  nunber  of  colwrm  in  active  window 

These  routines  return  the  number  of  rows  and  columns  (respectively)  in  the  active 
program  window.  Before  cell  files  can  be  read  or  written,  it  is  necessary  to 
known  how  marry  rows  and  columns  are  in  the  active  window.  For  example: 


int  nrows,  cols; 
int  row,  col; 

nrows  =  G_window_rows( ); 

ncols  =  G_window_cols( ); 

for  (row  =  0;  row  <  nrows;  row++) 

read  row  ... 

for  (col  =  0;  col  <  ncols;  col++) 
{ 

pocess  col  ... 

} 
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G_J9e(Lwilldow  (window)  set  the  active  viadow 

struct  Celljiead  ^window. 

This  routire  sets  the  active  window  from  window.  Setting  tiie  active  window 
does  not  change  the  WIND  file  in  the  database.  It  simply  changes  the  window 
for  the  duration  of  the  program.^ 

A  warning  message  is  printed  and  -1  returned  if  window  is  not  valid.  Otherwise  1 
is  returned. 

Note.  This  routirre  overrides  the  window  as  set  by  the  user.  Its  use  should  be 
very  limited  since  it  changes  what  the  user  normally  expects  to  happen.  If  this 
routine  is  not  called,  tiien  the  active  window  will  be  the  same  as  what  is  in  the 
user^  s  WIND  file. 

Warning.  Calling  this  routine  with  already  opened  ceU  files  has  some  side 
effects.  If  there  are  ceU  files  which  are  open  for  readmg,  they  will  be  read  into 
the  newly  set  window,  not  the  window  that  was  active  when  they  were  opened. 
However,  CELL  buffers  allocated  for  readmg  the  ceU  files  are  not  automaticaUy 
reaUocated.  The  program  must  reaUocate  them  explicitly.  Also,  tiis  routine  does 
not  change  the  window  for  ceU  files  which  are  open  for  writii^.  The  window  that 
was  active  when  the  open  occurred  stiU  applies  to  these  files. 

G _ge<;j9et_windo(W’  ( window)  get  the  active  window 

struct  Celljiead  ^window; 

(jets  the  values  of  the  currently  active  window  into  window.  If 
G_set_mndouAp.  79)  has  been  caUed,  then  the  values  set  by  that  caU  are  retrieved. 
Otherwise  the  user's  database  window  is  retrieved. 

Note  For  programs  that  read  or  write  ceU  data,  and  reaUy  need  the  fuU  window 
information,  this  routine  is  preferred  over  G_getjidndouAp.  77).  However,  since 
G_uindow_rows(p.78)  and  GjMndowj:olsip.7S)  return  the  number  of  rows  and 
columns  in  the  active  window,  the  programmer  should  consider  whether  or  not 
the  full  window  information  is  ready  needed  before  using  this  routine. 

The  foUowing  routines  retun  information  about  the  cartogr^hic  projection  and  zone. 
See  §9.2  Windoiv  \p.47\  for  more  information  about  these  values. 


^  Hswever,  the  iiew  window  setting  is  not  retained  across  the  UNIX  execi  )  call.  This 
implies  that  G_set_window(  )  cannot  be  used  to  set  the  window  for  a  program  to  be  executed 
using  the  ^steirt  )  or  popeni  )  routines. 
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G_4Xt:[iectkll  ( )  query  cartographic  projection 

This  routine  returns  a  code  indicating  the  projection  for  the  active  window.  The 
current  values  are: 

0  unreferenced  x,y  (imageiy  data), 

1  UTM, 

2  State  Hane.^^ 

Others  may  be  added  in  die  future, 
char  * 

G_prt|jectionjiailie  (proj)  query  cartographic  projection 

int  proj; 


Returns  a  pointer  to  a  string  which  is  a  printable  name  for  projection  code  prqj 
(as  returned  by  G_projectiorip.80)).  Returns  NULL  if  prqj  is  not  a  valid 
projectioa 

G_Z0ne  (  )  query  cartographic  rone 

This  routine  returns  the  zone  for  the  active  window.  The  noeaning  for  the  zone 
depends  on  the  projectiom  For  example  zone  18  for  projection  type  1  would  be 
ITIM  zone  18. 


12^.  Cell  FQe  Rrooessiiig 

Cell  files  are  the  heart  and  soul  of  GRASS.  All  analyses  are  performed  with  cell  file 
data  Because  of  diis,  a  suite  of  routines  which  process  cell  file  data  has  been 
provided. 

The  processing  of  cell  files  consists  of  deteniining  which  cell  file  or  files  are  to  be 
processed  (either  by  pronpting  the  user  or  as  specified  on  die  program  command  line), 
locatir^  the  cell  file  in  the  database,  opening  the  cell  file,  dynamically  allocating  i/o 
buffers,  reading  or  writing  the  cell  file,  closing  the  cell  file,  and  creating,  siqiport  files 
for  newly  created  cell  files. 

All  cell  file  data  is  of  type  CEUL^^,  which  is  defined  in  "gis.h". 


State  Bane  is  not  yet  fully  supported  in  GRASS. 

See  Appendix  B.  The  CELL  Data  Type  \p.  237}  for  a  discussion  of  the  CELL  type  and  how 
to  use  it  land  avoid  misusing  it). 
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12.&L  I¥iKnpdiig£ar  CdlFIks 

The  following  routines  interactively  prompt  tiie  user  for  a  cell  file  name.  In  each,  the 
prompt  string  will  be  printed  as  the  first  line  of  the  full  prompt  which  asks  the  user  to 
enter  a  cell  file  name.  If  prompt  is  the  empty  string  ""  then  an  appropiiate  pronpt 
will  be  siiostituted.  The  name  that  the  user  enters  is  copied  into  the  name  buffer. 
Tl^se  routines  have  a  built-in  ’list  capshility  which  dlows  the  user  to  get  a  list  of 
existing  cell  files. 

The  user  is  required  to  enter  a  valid  cell  file  name,  or  else  hit  the  RETURN  key  to 
cancel  the  request  If  the  user  enters  an  invalid  response,  a  message  is  printed,  and  the 
user  is  prompted  again.  If  the  user  cancels  the  request,  the  NULL  pointer  is  returned. 
Otherwise  the  mapset  where  the  cell  file  lives  or  is  to  be  created  is  returned.  Both  the 
name  and  the  mapset  are  used  in  other  routines  to  refer  to  the  cell  file. 

char  * 

G_a8k_OelL.old  (prompt,  name)  pronjt  for  existing  cell  fUe 

char  "pronjt; 
char  ’‘  name; 

Asks  the  user  to  enter  the  name  of  an  existing  cell  file  in  any  mapset  in  the 
database. 

char  * 

G_ask_odl_irL.map8et  (prompt,  name)  prorrpt  for  existing  cell  fUe 

char  pronpt; 
char  ’‘  name; 

Asks  the  user  to  enter  the  name  of  an  existing  cell  file  in  the  current  mapset 
char  ^ 

G_ask_oelLnew  ( prompt  name)  prorrpt  for  new  cell  file 

char  ‘  prompt 
ckir  ‘  name; 

Aslo^  the  user  to  enter  a  name  for  a  cell  file  which  does  not  exist  in  the  current 
mapset 

Here  is  an  example  of  how  to  use  these  routines.  Note  that  the  programmer  must 
handle  the  NULL  return  properly: 


’  ‘  Tlie  .size  of  name  should  be  large  enough  to  hold  any  GRASS  file  name.  Most  systems 
allow  file  I  Lime,'  to  be  quite  long.  It  is  lecoumended  that  name  be  declared  char  namefSOj . 
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char  *niapaet; 
char  name[50]; 

=  G_a6k_celLold("EiitBr  cell  file  to  be  processed",  name); 
if  (mapeet  ==  NULL) 
exittO); 


12.&2.  Findii^  Ceil  Files  in  the  Database 

Non-interactive  programs  cannot  make  use  of  the  interactive  promptii^  routines 
described  above.  For  example,  a  command  line  driven  program  may  require  a  cell  file 
name  as  one  of  the  command  arguments.  GRASS  allows  the  user  to  specify  cell  file 
names  (or  any  other  datEfoase  file)  either  as  a  simple  unqualified  name,  such  as  "soils", 
or  as  a  fully  qualified  name,  such  as  "soils  in  mapset",  where  wapset  is  the  mapset 
where  the  cell  file  is  to  be  found.  Often  only  the  unqualified  cell  file  name  is  provided 
on  the  command  line. 

The  following  routines  search  the  database  for  cell  files: 
char  * 

G_fiiicLoeil  (name,  mapset) 
char  * 

G_fintLoefl2  (name,  mapset) 

char  *name; 
char  *mapset; 

Look  for  the  cell  file  name  in  the  database.  The  rvapsA  parameter  c^  either  be 
the  empty  string  which  means  search  ail  the  map^ts  in  the  leer's  current 
m^)set  search  path,  or  it  can  be  a  specific  mapset  name,  which  means  look  for 
the  cell  file  only  in  this  one  mapset  (for  example,  in  the  current  mapset). 

If  foimd,  the  mapset  where  the  cell  file  lives  is  returned.  If  not  found,  the  NULL 
pointer  is  returned. 

The  difference  between  these  two  routines  is  that  if  the  user  specifies  a  fully 
qualified  cell  file  w'hich  exists,  then  G_find_cell2t )  modifies  name  by  removing 
the  "in  mapset"  while  G_find_cell( )  does  not^^  Normally,  the  GRASS 
programmer  need  not  wo  try  about  qualified  vs.  unqualified  names  since  aU  library 
routines  handle  both  forms.  However,  if  the  programmer  wants  the  name  to  be 

See  §4.7.2  Mapset  Secuc!>  Path  \p.  2o|  for  more  details  about  the  search  path. 

Be  warned  that  G_fincLcell2(  >  should  not  be  used  directly  on  a  command  line  argument, 
ance  modifying  argvf  |  may  ncjt  be  valid.  The  argument  should  be  copied  to  another  character 
buffer  wdiich  is  then  passed  to  (  ]_find_celI2t ). 


find  a  cell  file 
find  a  cell  file 
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iBtumed  unqualified  (for  displa^yii^  the  name  to  the  user,  or  stoiiitg  it  in  a  data 
file,  etc.),  then  G_fintLcell2( )  should  be  used. 

For  exanple,  to  find  a  cell  file  anywhere  in  the  database: 

char  name[50]; 
char  *nHpeet; 


if  ((m^)8et  =  G_find_ceII(name,"'’))  ==  NULL) 

/*  mt  found  *1 

To  check  that  the  cell  file  exists  in  the  current  mapset: 
char  name[50]; 


if  (G_find_ceU(name,G_m^jaet( ))  ==  NULL) 
/*  not  found  */ 


12.8.3.  Openii^  an  Existing’ Cell  File 

The  following  routine  opens  the  cell  file  name  in  mapset  for  reading. 

The  cell  file  name  and  mafiset  can  be  obtained  interactively  using 
G_ask_cell_old(p.81)  or  Gjcisk_ceUJn.jmpseiip.81),  and  non-interactively  using 
GJind_ceU(p.  82)  or  G_find_ceU2(p.82). 

G_opei\_celLold  (name,  mapset)  open  an  existing  cell  file 

char  *name; 
char  ^mapset; 

This  routine  opens  the  cell  file  name  in  mapset  for  reading. 

A  non-negative  file  descriptor  is  returned  if  the  open  is  successful.  Otherwise  a 
diagnostic  message  is  printed  and  a  negative  value  is  returned. 


TOs  routine  does  quite  a  bit  of  work  Since  GRASS  users  expect  that  all  cell  files 
will  be  resampled  into  the  current  window,  the  resiunpling  index  for  the  ceil  file 
is  prepared  by  this  routine  after  the'  file  is  opened.  Tlie  resarrpling  is  based  on  the 
active  program  window.^®  Preparation  required  for  reading  the  various  cell  file 
formats^^  is  also  done. 


Se-e  also  §i2.7  77/c  Window  [p  76\. 

Sf-f*  ^5.2  Grid  Cell  File  Format  \p.  24\  for  an  exj)lanation  of  the  vnrioie  cell  file  fonnats. 
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12.&4.  Greeting  and  Opening 

The  following  routines  create  die  new  cell  file  name  in  the  cunent  mapset^®  and  open 
it  for  writing,  Tlie  cell  file  name  should  be  obtained  interactively  using 
G_ask_peUjieuip.8i).  If  obtained  non-interactively  {e.g.,  fiom  the  command  line), 
GJegalJUemrmip.72)  should  be  called  first  to  make  sure  that  name  is  a  valid 
GRASS  file  name. 

Note.  It  is  not  an  ennr  for  name  to  already  exist  New  cell  files  are  actually  created 
as  temporaiy  files  and  moved  into  the  cell  directory  when  closed.  This  allows  an 
existing  cell  file  to  be  read  at  the  same  time  that  it  is  being  re-written  The  interactive 
routine  G_ask_ceU_neuip.8i)  guarantees  that  name  will  rx)t  exist  but  if  name  is 
obtained  from  the  command  line,  name  may  exist  In  fids  case  GJind_cell(p.82)  could 
be  used  to  see  if  name  exists. 

Warning  However,  there  is  a  subtle  trap.  The  temporaiy  file,  which  is  created  using 
Gjempfileip.  108),  is  named  using  the  current  process  id.  If  the  new  cell  file  is  opened 
by  a  parent  process  which  exits  after  creating  a  child  process  using  fork(  the  cell 
fUe  may  never  get  created  since  the  temporaiy  file  would  be  associated  with  the  parent 
process,  not  the  child.  GRASS  management  automatically  removes  temporary  files 
-  associated  with  processes  fiiat  are  no  longer  running.  If  foik( )  must  be  used,  the  safest 
course  of  action  is  to  create  the  child  first,  thai  open  the  cell  file.  (See  the  disc'jssion 
under  GjenjjfUeip.  108)  for  more  details.) 

G_(^ien_oeILnew  ( name)  open  a  mw  cell  file  (sequential) 

char  *name; 

Oeates  and  opens  the  cell  file  name  for  writing  by  G_put_niap_row{p.88)  which 
writes  the  file  row  by  row  in  sequential  order.  The  cell  file  data  will  be 
compressed  as  it  is  written 

A  noi>negative  file  descriptor  is  returned  if  the  open  is  successful.  Otherwise  a 
diagnostic  message  is  printed  aixl  a  negative  value  is  returned. 


GRASS  doeai’t  allow  files  to  be  cneatefi  oiitade  the  current  tn^jspt.  See  §4  7  Database 
Access  Rules  \p.20]. 

See  also  GJbrkip  iis). 
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G_open_odljnewjOTdk]ni  (name)  open  a  new  cell  file  (mndoin 

char  *name; 

Creates  and  opens  the  cell  file  name  for  writii^  by 
Gj)utj7}ap_mw_randorTip.88)  which  allows  writing  the  cell  file  in  a  random 
fa^oa  The  file  will  be  created  uncompressed.^ 

A  non-negative  file  descriptor  is  returned  if  die  open  is  successful.  Otherwise  a 
diagnostic  message  is  printed  and  a  negative  value  is  returned. 

G_open_cdLjiew_unOMnpre99ed  (name)  open  a  new  cell  file  (unconpressed) 

char  *name; 

Oeales  and  opens  the  cell  file  name  for  writing  by  G_put.jrap_roiu{p.  S8)  which 
writes  the  file  row  by  row  in  sequential  order.  The  ceU  file  will  be  in 
uncompressed  format  when  closed. 

A  non-negative  file  descriptor  is  returned  if  the  open  is  successful.  Otherwise  a 
warning  message  is  printed  on  stderr  and  a  n^ative  value  is  retunied. 

General  use  of  this  routine  is  not  recommended.^^  This  routine  is  provided  so  the 
uncorrpress  program  can  create  uncompressed  cell  files. 


12.8.5.  AUocating  CeU  I/O  Buffers 

Snce  there  is  no  pre-defined  limit  for  the  number  of  columns  in  the  window, buffers 
which  are  used  for  reading  and  writing  cell  data  must  be  dynamically  allocated. 


Nor  will  the  file  get  automatically  compressed  when  it  is  closed.  If  a  corrpresseci  file  is 
desired,  it  can  be  compressed  explicitly  after  cloang  by  a  system  call; 
systemi "compress  imme"). 

At  present,  automatic  cell  file  compression  will  create  files  which,  in  most  cases,  :iie 
smaller  than  if  ftiey  were  uncompressed.  In  certain  cases,  the  compressed  cell  file  irgy  be 
larger.  This  can  happen  with  imagery  data,  which  don’t  compress  well  at  all.  Ifcwever,  the 
aze  difference  is  usually  anall.  Siire  future  enhatKements  to  the  compresaon  metJiod  may 
imfMDve  compression  for  imagery  data  as  well,  it  is  best  to  create  compressed  cell  files  in  ail 
cares. 

See  G^wiruhw_colsin  7«)  to  find  the  number  of  colurms  in  the  window. 
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CELL* 

G_allocate-OdlL.bllf  ( )  allocate  a  cell  buffer 

This  routine  allocates  a  buffer  of  type  CELL  just  large  enou^  to  hold  one  row  of 
cell  rfata  (based  on  the  nuixber  of  columns  in  the  active  window). 

CELL  *cell; 

cell  =  G_allocatB_celLbuf(); 

If  larger  buffers  are  required,  die  routine  G_nnlloc(p.  76)  can  be  used. 

If  sufficient  memory  is  not  available,  an  error  message  is  printed  and  exit( )  is 
called. 

G_zero_oeIL.buf  (buf)  zero  a  cell  buffer 

CELL  *buf; 


This  routines  assigns  each  member  of  the  cell  buffer  arr^  buf  to  zero.  It 
assumes  that  buf  has  been  allocated  using  G_allocate_ceU_bi^.86). 


12.8.6.  Rearfing  Cdl  Files 

Cell  file  data  can  be  thought  of  as  a  two-dimensional  matrix.  The  routines  described 
below  read  one  full  row  of  (he  matrix.  It  should  be  understood,  however,  that  the 
number  of  rows  and  columns  in  the  matrix  is  determined  by  the  window,  not  the  ceD 
file  itself.  Cell  file  data  is  always  read  resampled  into  the  window.^  This  allows  the 
user  to  specify  the  coverage  of  the  database  during  analyses.  It  also  allows  databases 
to  consist  of  cell  files  which  do  not  cover  exactly  the  same  area,  or  do  not  have  the 
same  grid  cell  resolution  When  cell  files  are  resampled  into  the  window,  they  all 
"look"  the  same. 

Note.  The  rows  and  columns  are  specified  "C  style",  i.e.,  starting  with  0. 


Tlie  GRASS  window  is  discuEsed  from  a  user  perspective  in  §9.2  Window  {p.  47]  and  from 
a  programmer  perspective  in  §22.7  The  WiacL/w  !p.  7ffj.  Tlie  routines  which  are  commonly  used 
to  detemine  the  nurrber  of  rows  and  columns  in  the  window  are  G_uUndouj_rows(p.  78)  and 
GjuindowjcoMp  78). 
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G_fietjiiapjtiw  (fd,  cell,  row)  read  a  ceU  file 

intfd; 

CELL  *cell; 
int  row. 

This  routine  reads  the  specified  raw  from  the  cell  file  open  on  file  descriptor  fd 
(as  returned  by  G_open_ceU^ldip.83))  into  the  cell  buffer.  Ihe  odl  buffer  must 
be  dynamically  allocated  large  enough  to  hold  one  full  row  of  cell  dfito  It  can  be 
allocated  using  GjilIocate_ceUJbiuf{p.86). 

This  routine  prints  a  diagnostic  niesssge  and  returns  -1  if  there  is  an  error  reading 
the  cell  file.  Otherwise  a  non-n^ative  value  is  returned. 

G_getjnrapjrOWJIlC»nask  (fd,  cell,  row)  read  a  cell  file  (without  rmskirig) 

int  fd; 

CELL  *cell; 
int  row; 

This  routine  reads  the  specified  row  from  the  cell  file  open  on  file  descriptor  fd 
into  the  oefl  buffer  like  G_geunap_row( )  does.  The  difference  is  that  masking 
is  suppressed.  If  the  user  has  a  mask  set,  G_get_msp_jow( )  will  apply  the  mask 
but  G_geLjnap_row_nomask( )  will  ignore  it 

This  routine  prints  a  diagnostic  message  and  returns  -1  if  there  is  an  error  reading 
the  cell  file.  Otherwise  a  non-negative  value  is  returned. 

Note.  Ignoring  the  mask  is  not  generally  acceptable.  Users  expect  the  mask  to 
be  applied.  However,  is  some  cases  ignoring  the  made  is  justified.  Fbr  example, 
the  GRASS  programs  Gdesenbe,  which  reads  the  cell  file  directly  to  report  all 
data  values  in  a  cell  file,  or  Gshpe. aspect,  which  produces  slope  and  aspect  from 
elevation,  ignore  both  the  mask  and  the  window.  However,  the  number  of 
GRASS  programs  which  do  this  should  be  minimal.  See  §9.2  Mask  \p.48\  for 
more  information  about  the  mask. 


12.8.7.  Writii^CeUFUes 

The  routines  described  here  write  cell  file  data 
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G_pi]t.JinpLrQW  (fd,  buf)  urUe  a  cell  fk  (sequential) 

intfd; 

CELL  *buf; 

This  routine  writes  one  row  of  cell  data  from  buf  to  tbe  cell  file  open  on  file 
descriptor  fd  The  cell  file  must  have  been  opened  with  G_opeTij:ell_neuip.84). 
The  cell  buf  must  have  been  allocated  large  enou^  for  the  window,  peahaps 
uang  G_pUocate_pellJ)uf[p.86). 

If  there  is  an  emor  writing  the  cell  file,  a  warning  message  is  printed  and  -1  is 
returned.  Otherwise  1  is  returned. 

Note.  The  rows  are  written  in  sequential  order.  The  first  call  writes  row  0,  the 
second  writes  row  1,  etc.  The  following  example  assumes  that  die  cell  file  name 
is  to  be  created: 

int  fd,  row;  nrows; 

CELL*buf; 

fd  =  G_open_celLnew  tnarne); 
if  (fd  <  0) 

/*  oops  -  can’t  open  cell  file  */ 

buf  =  G_alloc*tfB_celLbuf(); 
nrows  =  G_window_rows( ); 
for  (row  =  0;  row  <  nrows;  row++) 

{ 

A  prepare  data  for  this  row  into  buf  */ 

/*  write  the  data  for  the  row  */ 

G_puLm£p_row  (fd,  buf); 

> 


G_putjnap_Jtlw_xandom  (fd,  buf,  row,  col,  ncells)  luiie  a  cell  file  (randorn) 

int  fd; 

CELL  *buf; 
int  ro  w,  col,  ncells; 

This  routine  allows  random  writes  to  the  cell  file  open  on  file  descriptor  fd  The 
cell  file  must  have  been  opened  using  G_openj:eU_jTew_randorrip.85).  The  cell 
buffer  buf  contains  noeUs  columns  of  data  and  is  to  be  written  into  the  cell  file  at 
the  specified  row,  starting  at  column  ooL 
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12.aa  Cl<Mi«  Cell  Files 

All  cell  files  are  closed  by  one  of  tiie  following  routines,  whether  opened  for  reading 
or  for  writing. 

G_doee_cefl  (fd)  close  a  cell  file 

intfd; 


The  cell  file  opened  on  file  descriptor  fd  is  closed.  Memory  allocated  for  cell 
processing  is  freed.  If  open  for  writing,  skeletal  sipport  files  for  the  new  cell  file 
are  created  as  well. 

Note  If  a  program  wants  to  explicitly  write  siqpport  files  (e.g.,  a  specific  color 
table)  for  a  cell  file  it  creates,  it  must  do  so  after  the  cell  file  is  closed.  Odierwise 
the  close  will  overwrite  the  sipport  files.  See  §i2.9  Map  Layer  Support  Routines 
fp.  S9]  for  routines  which  write  cell  support  files. 

G_unqpen_0efl  (fd)  unopen  a  ceU  file 

intfd; 


Tte  cell  file  opened  on  file  descriptor  fd  is  closed.  Memory  allocated  for  cell 
processing  is  freed.  If  open  for  writirig,  the  cell  file  is  not  created  and  die 
temporary  file  created  wh^  the  cell  file  was  opened  is  removed  (see  ^12.8.4 
Creating  and  Opening  New  Cell  Files  (p.S^l). 

This  routine  is  useful  when  errors  are  detected  and  it  is  desired  to  not  create  the 
new  cell  file.  While  it  is  true  that  the  cell  file  will  not  be  created  if  the  program 
exits  without  closing  the  file,  the  temporary  file  will  not  be  removed  at  program 
exit  GRASS  database  management  will  eventually  remove  the  temporary  file, 
but  the  file  can  be  quite  large  and  will  take  i?)  disk  space  until  GRASS  does 
remove  it  Use  this  routine  as  a  courtesy  to  the  user. 


12.9.  Map  La^  SiqipGrt  Roudnes 

GRASS  map  layers  have  a  numba*  of  sn)port  files  associated  with  diem.  These  files 
are  discussal  in  detail  in  §5  Grid  Cell  Maps  \p.23].  The  support  files  are  the  ceU 
header,  the  category  file,  the  color  table,  the  history  file,  ard  the  range  file.  Each 
support  f  ile  has  its  own  data  structure  and  associated  routines. 


12.9.1.  Cell  Header  File 

TIk-  cell  header  file  contains  infonnation  describirig  the  geographic  extent  of  the  map 
layer,  ily  grid  cell  resolution,  and  the  format  used  to  store  the  data  in  the  ceU  file.  The 
fomiat  of  this  file  is  described  in  §5.3  CeU  Header  Format  \p.26\.  The  routines 
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desciibed  below  use  die  CeUJ\ead  structuie  which  is  shown  in  detaU  in  §i2.i7  GIS 
Library  Data  Structures  [p.  118\. 

G  get  orilhd  (name,  mapset;  cellhd)  read  the  cell  header 

char  *name; 

char  *mapset; 

struct  CelL-H^  *cellhd; 

The  cell  header  for  the  cell  file  name  in  the  specified  mapset  is  read  into  the 
oellhd  structure. 

If  there  is  an  error  readily  the  cell  heada*  file,  a  diagnostic  message  is  printed 
and  -1  is  returned.  Otherwise,  0  is  returned. 

Note.  If  die  cell  file  is  a  reclass  file,  the  cell  header  for  the  referenced  cell  file  is 
read  instead.  See  §5.5-2  Beclass  Format  (p.271  for  information  about  reclass  files, 
and  GJs_reclass(p.  91)  for  distingmshing  reclass  files  from  r^ular  cell  files. 

Note.  It  is  not  necessary  to  get  the  cell  header  for  a  map  layer  in  order  to  read 
the  cell  file  data.  The  routines  which  read  cell  file  data  automatically  retrieve  the 
cell  header  information  and  use  it  for  resampling  the  cell  file  data  into  the  active 
window.^  If  it  is  necessary  to  read  the  cell  file  directly  without  resarapliiig  into 
the  active  window,^®  dien  the  cell  header  can  be  used  to  set  the  active  window 
usir^  G^tjbuindouip.  79), 

G_put_cdlhd  (name,  cellhd)  write  the  cell  header 

char  *name; 

struct  Celljiead  *  cellhd; 

This  routine  writes  the  information  from  the  oeflhd  structure  to  the  cell  header 
file  for  the  map  layer  name  in  the  current  mapset 

If  there  was  an  error  creating  the  cell  header,  -1  is  returned.  No  diagnostic  is 
printed.  Otherwise,  1  is  returned  to  indicate  success. 

Note.  Programmers  should  have  no  reason  to  use  this  routine.  It  is  by 
G_close_cell(p.89)  to  give  new  cell  files  correct  cell  header  files,  and  by  the 
siq)})ort  program  to  give  users  a  means  of  creating  or  modifying  cell  headers. 


See  ij/2.7  The  Window  \p  761. 

^  but  see  §5  Window  and  Mask  \p.47\  for  a  discusaon  of  when  this  should  and  drtuld  not 
be  done. 
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GJaJ«!iass  (name,  mapset,  r_j]aine,  r_ji£pset)  reclass  fie? 

char  *name; 
char  *maqpset; 
char  *r_name; 
char  *r_jnapset; 

Hiis  function  determines  if  the  cell  file  name  in  mapset  is  a  reclass  file.  If  it  is, 
dien  the  name  and  mapset  of  the  referenced  cell  file' are  copied  into  the  rename 
and  r_map8et  buffers. 

Returns  1  if  name  is  a  reclass  file,  0  if  it  isn’t,  and  -1  if  there  was  a  problem 
readiiig  the  cell  header  for  name. 


12.9.2.  Cell  Category  File 

GRASS  map  layers  have  category  labels  associated  with  them  The  category  file  is 
structured  so  that  each  category  in  the  cell  file  can  have  a  one-line  desciiptioa  The 
format  of  this  file  is  described  in  §5.4  Cell  Category  File  Format  [p.28]. 

The  routines  described  below  manage  the  category  file.  Some  of  thorn  use  the 
Categories  structure  which  is  described  in  §12.27  GIS  Library  Data  Structures  \p.  118]. 


12.9.2.1.  Readiiig  and  Writing  the  Cell  Category  File 
The  following  routines  read  or  write  the  category  file  itself: 

G_iTead_cats  ( name,  mapset  cats)  read  cell  category  file 

char  *name; 

char  ^mapset 

struct  Categories  cats; 

The  category  file  for  cell  file  name  in  mapset  is  read  into  the  cats  structure. 

If  there  is  an  error  reading  the  category  file,  a  diagnostic  message  is  printed  and 
-1  is  returned.  OliK'iwise,  0  is  returned. 
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G_\wite_cal8  (name,  cats)  vrite  cell  category  foe 

char  *name; 

struct  Cati^ries  *cabs; 

Writes  the  category  file  for  the  cell  file  name  in  the  current  mapset  from  the  cats 
structure. 

Returns  0  if  successful.  Otherwise,  -1  is  returned  (no  diagnostic  is  printed), 
char* 

G_get_ceiLtitle  (name,  mapset)  get  cell  title 

char  *name; 
char  *mapset; 

If  only  the  m^  layer  tide  is  needed,  it  isn’t  itecessary  to  read  the  entire  category 
file  into  metmry.  'Ihis  routine  gets  the  title  for  ceU  file  name  in  mapset  directly 
from  the  category  file,  and  returns  a  pointer  to  the  title.  A  l^al  pointer  is  always 
returned.  If  the  map  layer  doesn’ t  lave  a  tide,  then  a  pointer  to  the  empty  string 
""is  returned. 


char  * 

G_put_odLtitle  (name,  tide)  change  cell  title 

char  *name; 
char  *tide; 

If  it  is  only  desired  to  charge  ti^  tide  for  a  map  layer,  it  isn’ t  necessary  to  read 
the  entire  category  file  into  memory,  change  the  tide,  and  rewrite  the  cat^ory 
file.  This  routine  changes  the  title  for  the  celt  file  name  in  the  current  mapset 
direcdy  in  the  cat^ory  file.  It  returns  a  pointer  to  tire  tide. 


12.9,2.2.  Querying  and  Changing  the  Cat^ories  Structure 

Tte  followiiig  routines  query  or  modify  the  information  contained  in  the  cat^ory 
structure: 
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char  * 

G_gB(Lcat  (n,  cats)  get  a  category  label 

CELL  n; 

struct  Cafc^iies  *cals; 

Ihis  routine  looks  i^)  category  n  in  the  cats  structure  and  returns  a  pointer  to  a 
string  which  is  the  label  for  the  category.  A  l^al  pointer  is  always  returned.  If 
the  cat^ory  doesn’t  exist  in  cats^  tiien  a  pointer  to  the  empty  string  ""  is 
returned. 

Warmn^  The  pointer  that  is  returned  points  to  a  hidden  static  buffer. 
Successive  calls  to  G_get_cat( )  overwrite  this  buffer. 

char  * 

G_ge<;_cals_tifie  (cals)  get  title  from  category  stnctiae 

stiuct  Cat^ries  *cats; 

Map  layers  store  a  one-line  tide  in  the  eatery  structure  as  well.  This  routine 
returns  a  pointer  to  the  title  contained  in  the  cats  structure.  A  legal  pointer  is 
always  returned.  If  the  map  layer  doesn’ t  have  a  tide,  then  a  pointer  to  the  empty 
string  ""  is  returned. 

G_irat_cals  (n,  tide,  cats)  imtialux  category  stricture 

CELL  n; 
char  *titie; 

stiuct  Cat^ories  *cats; 

To  construct  a  new  cat^oiy  file,  the  structure  must  first  be  initialized.  This 
routine  initializes  the  cats  structure,  and  copies  the  title  into  the  structure.  The 
number  of  categories  is  set  initially  to  n. 

For  example: 

struct  Categories  cate; 

GJnit_cate  (  (CELL)0, &cate); 
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Gj9et_CEi  (n,  label,  cats)  set  U  category  label 

CELL  n; 

char  *label; 

struct  Categories  *cats; 

The  labd  is  copied  into  the  cats  structure  for  cat^iy  n. 

G_set_cats_title  (title,  cats)  set  title  in  category  structure 

char  *title; 

struct  Categories  *cats; 

The  tine  is  copied  into  d£  cats  stmcture. 

G_ftee_catS  (cats)  free  category  structure  memoty 

struct  Cat^ories  *cats; 

FVees  memory  allocated  by  G_read_£atsip.9l),  GJrit_cats{p.93)  and 
G_set_catip.94). 


12.9.3.  CeU  Color  Table 

GRASS  m^  l^ers  have  colors  associated  with  them.  The  color  tables  are  structured 
so  that  each  category  in  the  cell  file  has  its  own  color.  The  format  of  this  file  is 
described  in  §5.5  Cell  Color  TbUe  Format  \p.28]. 

The  following  routines  read,  create,  modify,  and  write  color  tables.  They  use  the 
Colors  structure  which  is  described  in  detail  in  §22.17  GIS  Library  Data  Structures 

\p.  1181 


G_read_ool€rs  (name,  mapset,  colors)  read  map  layer  color  table 

char  *name; 
char  *mapset; 
struct  Colors  *  colors; 

Tlie  color  table  for  the  cell  file  name  in  the  specified  meiset  is  read  into  the 
errors  structure. 

If  the  data  l^er  has  no  color  table,  a  default  color  table  is  generated  and  0  is 
returned.  If  there  is  an  error  readirrg  the  color  table,  a  diagnostic  message  is 
printed  and  -1  is  returned.  If  the  color  table  is  read  ok,  1  is  returned. 
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G_wrilCL.OQionB  (name,  mapeet,  colors)  write  rmp  layer  color  table 

char  *name; 
char  *mapset; 
struct  Colors  *colors; 

The  color  table  is  written  for  the  cell  rile  name  in  the  speciried  nEfset  from  die 
colors  structure. 

If  there  is  an  error,  -1  is  returned.  No  diagnostic  is  printed.  Otherwise,  1  is 
returned. 

The  odors  structure  must  be  created  properiy,  i.e.,  GJ,rit_colors(p.  96)  to 
initialize  the  structure  and  G_set_color(p.96)  to  set  the  category  colors.^ 

Note.  The  calling  sequence  for  this  function  deserves  special  attention  The 
mapset  parameter  seems  to  imply  that  it  is  possible  to  overwrite  the  color  table 
for  a  cell  file  which  is  in  another  mapset  However,  this  isn’t  what  actually 
happens.  It  is  very  useful  for  users  to  create  thdr  own  color  tables  for  ceU  files 
in  other  m^rsets,  but  without  overwriting  other  users’  color  tables  for  the  same 
cell  file.  If  nGqnet  is  the  current  mapset,  then  the  color  file  for  name  will  be 
overwritten  by  the  new  color  table.  But  if  mapset  is  not  the  current  m^)set,  then 
the  color  table  is  actually  written  in  tiie  cument  mapset  under  the  oolr2  element 
as:  co]i2/rnapset/mnie. 

G_get_oolor  (cat,  red,  green,  blue,  colors)  get  a  category  color 

CELL  cat 
int  *red; 
int*green; 
int  *blue; 

struct  Colors  *colors; 

The  red,  green,  and  Wue  intensities  for  the  color  associated  with  category  cat  are 
extracted  from  the  oolors  structure.  The  intensities  will  be  in  the  range  0-255. 


These  routines  are  called  by  higher  level  routines  which  read  or  create  entire  color  tables, 
such  as  G^read  rolorsip  .'M)  or  G_rmke_color_?arrp(p  .V7). 
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G_int-OOkV8  (colors)  imtialm  color  structure 

struct  Colors  *colors; 

The  oolovs  structune  is  initialized  for  sidbsequent  calls  to  G_$et_coloTip.96). 

G_setLOolor  (cat,  red,  green,  blue,  colors)  set  a  category  color 

CELL  cat; 
int  red; 
int  green; 
int  blue; 

struct  Colors  *colors; 

The  red,  green,  and  Wue  intensities  for  the  color  associated  with  category  cat  are 
set  in  the  colors  structure.  The  intensities  must  be  in  the  range  0-255.  Values 
below  zero  are  set  as  zero,  values  above  255  are  set  as  255. 

Note.  The  colors  structure  must  have  been  initialized  by  GJmtj:olors{p  96). 

Gjfree_colors  ( colors)  free  color  stnctwe  werrory 

Struct  Colors  ^colors; 

The  dynamically  allocated  memory  associated  with  the  colors  structure  is  freed. 

Note.  This  routine  may  be  used  after  Gj^adjpolorsip.94)  as  well  as  after 
GJmt_colors{p.  96). 

The  following  routines  generate  entire  color  tables.  The  tables  are  loaded  into  a  coIcmts 
structure  based  on  a  range  of  category  values  from  min  to  max.  The  range  of  values 
can  be  obtained,  for  example,  using  G_read_range{p.99). 

Note.  The  color  tables  are  generated  without  information  about  any  particular  cell  file. 
These  color  tables  may  be  created  for  a  cell  file,  but  they  may  also  be  generated  for 
loading  graphics  colors. 

These  routines  return  -1  if  nin  is  greater  than  max,  1  otherwise. 
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G_jiKikeL.aGpect_calors  (colors,  min,  max)  nube  aspect  colors 

stiuct  Colore  *colore; 

CELL  mill,  max; 

(generates  a  color  table  for  aspect  data. 

G_make_cdor_j:^Hnp  (colore,  min,  max)  rmhe  color  ranp 

stmct  Colors  *colors; 

CELL  min,  max; 

Generates  a  color  table  with  3  sections;  red  only,  green  only,  and  blue  only,  each 
increasing  from  none  to  full  intensity.  This  table  is  good  for  continuous  data  like 
elevation 

G_make_color_wave  (colors,  min,  max)  rrntx  color  move 

stiuct  Colors  *colore; 

CELL  min,  max; 

(Generates  a  color  table  with  3  sections:  red  only,  green  only,  and  blue  only,  each 
increasing  from  none  to  full  intensity  and  back  down  to  none.  This  table  is  good 
for  continuous  data  like  elevation 

Note.  This  routine  requires  that  the  $(MATHLIB)  be  loaded  as  well. 

G_inakcLgrey_scale  (colors,  min,  max)  maJx  linear  grey  scale 

struct  Colors  *colore; 

CELL  min  niax; 

Generates  a  grey  scale  color  table.  Each  color  is  a  level  of  grey,  increasing  from 
black  to  white. 

G_make_jrainbow_oolo*s  (colors,  min  max)  rm/x  rairbow  colors 

struct  Colors  *colore; 

CELL  min  max; 

Generates  a  color  table  based  on  rainbow  colors.  The  table  generated  here  uses 
yellow,  green  blue,  indigo,  violet,  red.  (Normal  rainbow  colors  are  red,  orange, 
yellow,  green  blue,  indigo,  and  violet)  This  table  is  good  for  continuous  data 
like  elevation 


§  12  GIS  LilM"ary 


-98- 


-98- 


G.^iiiAaej:sndanL.oolor8  (colors,  min,  max)  make  randomcolors 

struct  C!olors  *colors; 

CELL  min.  max; 

(Glenerates  random  colors.  Good  as  a  first  pass  at  a  color  table  for  nominal  data 

G_nBke_recLyELgi*n  (colors,  min,  max)  make  redyelhw^en colors 

struct  Colors  ^colors; 

CELL  min,  max; 

(jenerates  a  color  table  similar  to  what  G.j7iahe_rcur}bow_colors{p.97)  creates, 
except  that  the  table  starts  at  red,  passes  through  yellow,  and  ends  with  green. 


12.9.4.  CeO  Histoty  File 

The  history  file  contains  documentary  information  gbout  the  cell  file:  who  created  it, 
when  it  was  created,  what  was  the  original  data  source,  what  information  is  contained 
in  the  cell  file,  etc.  This  file  is  discussed  in  §5.6  Cell  Hstory  File  [p.29]. 

The  following  routines  manage  this  file.  They  use  the  Hstory  structure  which  is 
described  in  §22.i7  GIS  Library  Data  Structures  Ip.  118]. 

Note  This  structure  has  existed  relatively  unmodified  since  the  inception  of  GRASS. 
It  is  in  need  of  overhaul.  Programmers  should  be  aware  that  future  veraons  of  GRASS 
may  no  longer  si^rport  either  die  routines  or  the  data  structure  which  siqiport  the 
history  file. 

G_i«adLhistiory  (name,  mapset,  history)  read  cell  history  file 

char  *name; 

char  *mapset; 

struct  Hstory  ^history; 

This  routine  reads  the  history  file  for  the  cell  file  name  in  mapset  into  the 
Wstoay  structure. 

A  diagnostic  message  is  printed  and  -1  is  returned  if  there  is  an  error  reading  the 
history  file.  Otherwise,  0  is  returned. 
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G_^writOB8tocy  (name,  histoiy)  write  cell  history  file 

char  *name; 

stnict  Hstory  *histDry; 

This  routine  writes  the  histoiy  file  for  the  cell  file  name  in  the  current  mapset 
from  the  histoy  structure. 

A  diagnostic  message  is  printed  and  -1  is  returned  if  there  is  an  error  writing  the 
histoiy  file.  Otherwise,  0  is  reuimed. 

Note.  The  histcty  structure  should  first  be  initialized  using 
G_shortJiistory(p.  99) . 

G_jshoirtJiistoty  (name,  type,  history)  imtialvx  history  stmctwe 

char  *name; 
char  *type; 

struct  Hstory  ^history; 

This  routine  initializes  the  history  structure,  recording  the  dale,  user,  program 
name  and  the  cell  file  name  structure.  The  type  is  an  anachronism  from  earlier 
versions  of  GRASS  and  should  be  specified  as  "cell". 

Note  This  routine  only  initializes  the  data  structure.  It  does  not  write  the  history 
file. 


12.9.5.  Cell  Range  File 

The  following  routines  manage  the  cell  rar^e  file.  This  file  contains  the  minimum  and 
maximum  values  found  in  the  cell  file.  The  format  of  this  file  is  described  in  §5.7 
Cell  Range  File  \p.29\. 

The  routines  below  use  the  Range  data  structure  which  is  described  in  §22.17  GIS 
library  Data  Sb'uctnres  \p.  118\. 

G j^acLrange  ( name,  mapset,  range)  lead  cell  range 

char  *nanie; 
char  *mapseti 
struct  Range  ^  range; 

This  routine  reads  the  range  information  for  the  cell  file  name  in  mapset  into  the 
rai^  structure. 

A  diagnostic  mcs.sage  is  printed  and  -1  is  returned  if  there  is  an  error  reading  the 
range  file.  Otherwise,  0  is  returned. 
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G  ^W^taJrullBD  (name,  mngO)  luitr  cell  rcL-tge 

char  *name; 
struct  Range  *range; 

This  loutiiB  writes  tte  larrge  information  for  the  cell  file  name  in  the  current 
mapset  from  the  range  structure. 

A  diagnostic  message  is  printed  and  -1  is  returned  if  tiiere  is  an  error  writing  the 
range  file.  Otherwise,  0  is  returned. 

Tl«  range  structure  must  be  initialized  and  tqrdated.  uang  the  following  routines: 

G_jrit_nange  (range)  initialize  range  structure 

Struct  Range  *range; 

Initializes  the  range  structure  for  updates  by  G_ijpdate_rcuTge(p.  lOO)  and 
GjyywjLtpdalejxmgeip.  100). 

G_l^xtatejrange  (cat,  range)  update  range  structure 

CELL  cat; 
struct  Range  *range; 

Compares  the  cat  value  with  the  raintraum  and  maximum  values  in  the  rar^ 
structure,  modifying  the  raonge  if  cat  extends  the  range. 

G_row_l5Klate_j:angB  (cell,  n,  range)  update  range  structure 

CELL  *cell; 
int  n; 

struct  Range  *range; 

This  routine  updates  the  range  data  just  like  G_updnte_j-ange{p.  100),  but  for  n 
values  from  the  oefl  array. 


12.10.  Vectc**  File  FVooeasang 

ITie  GIS  library  contains  some  functions  related  to  vector  file  processing.  These 
include  prompting  the  user  for  vector  files,  locating  vector  files  in  the  database, 
opening  vector  files,  and  a  few  others. 

Note  Most  vector  file  processing,  ho'vever,  is  handled  by  routines  in  the  Dig  library, 
which  is  described  in  §25  Dig  Library  Ip.  123]. 
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12.10.1.  RmiiUng  fir  Vector  Files 

The  following  routines  interactively  prompt  the  user  for  a  vector  file  name.  In  each, 
the  proinit  string  will  be  printed  as  the  first  line  of  the  full  prompt  which  asks  the 
user  to  enter  a  vector  file  name.  If  pronopt  is  tiie  empty  string  then  an  appropriate 
prompt  will  be  substituted.  The  name  that  the  user  enters  is  copied  into  the  name 
buffer.^  These  routines  have  a  built-in  ’list  cspability  which  allows  the  user  to  get  a 
list  of  existing  vector  files. 

The  user  is  required  to  enter  a  valid  vector  file  name,  or  else  hit  the  RETURN  key  to 
cancel  the  request  If  the  user  enters  an  invalid  response,  a  message  is  printed,  and  the 
user  is  prompted  again.  If  the  user  cancds  the  request  the  NULL  pointer  is  returned. 
Otiierwise  Ak  mapset  where  the  vector  file  lives  or  is  to  be  created  is  returned.  Both 
the  name  and  the  mapset  are  used  in  other  routines  to  refer  to  the  vector  file. 


char  * 

G_a8k_vector_cJd  (prompt,  name)  pronpt  for  an  existing  vector  file 

char  *name; 
char*mapset; 

Asks  the  user  to  enter  the  name  of  an  existing  vector  file  in  any  mapset  in  the 
database. 

char  * 

G_afil5_vecterJlitjnapeet  (prompt,  name)  prompt  for  an  existing  vector  file 

char  *namB; 
char  *mapset; 

Asks  the  user  to  enter  the  name  of  an  existing  vector  file  in  the  current  mapset 


char  * 

G_ask_vector_Iiew  ( prompt  name)  pronpt  for  a  new  vector  file 

char  *name; 
char  *mapset; 

Asks  the  user  to  enter  a  name  for  a  vector  file  which  does  not  exist  in  the  current 
m^)set 

Here  is  an  example  of  how  to  use  these  routines.  Note  that  the  programmer  must 
handle  the  NULL  return  properiy: 


TTie  size  of  name  should  be  large  enough  to  liold  any  GRASS  file  name.  Most  systems 
allow  file  names  to  be  quite  long.  It  is  teconmended  that  name  be  declared  chw  mrmfSOf 
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char  *iiiBp8et; 
char  name[50]; 

inBp8et=  G:_adt.vector_old("ElilBr  vector  file  to  be  processed",  name); 
if  (mapeet  ==  NULL) 
exiUO); 


12.10^  Rn^ng  Vector  Flies  in  tile  Database 

Non-interactive  programs  cannot  make  use  of  the  interactive  prompting  routines 
described  above.  For  example,  a  command  line  driven  program  may  require  a  vector 
file  name  as  one  of  the  command  arguments.  GRAl^  allows  the  user  to  specify 
vector  file  names  (or  any  odier  database  file)  either  as  a  simple  unqualified  name,  such 
as  "roads",  or  as  a  fully  qualified  name,  such  as  "roads  in  rnapset",  where  mapset  is 
the  mapset  where  die  vector  file  is  to  be  found.  Often  only  die  unqualified  vector  file 
name  is  provided  on  die  command  line. 

The  following  routines  search  the  database  for  vector  files: 

G_fimLvector  (name,  mapset) 

G_find_vBctor2  (name,  mapset) 

char  *name; 
char  *m^set; 

Look  for  the  vector  file  name  in  the  database.  The  mapset  parameter  can  either 
be  the  empty  string  which  means  search  all  die  mapsets  in  the  useris  current 
mapset  search  palh,^  or  it  can  be  a  specific  mapset  name,  which  means  look  for 
the  vector  file  only  in  this  one  mapset  (for  example,  in  the  current  ma|»et). 

If  found,  the  mapset  where  the  vector  file  lives  is  returned.  If  not  found,  the 
NULL  pointer  is  returned. 

The  difference  between  these  two  routines  is  that  if  the  user  specifies  a  fully 
qualified  vector  file  which  exists,  then  G_fincLvectoi2( )  modifies  name  by 
removing  the  "in  mapset"  while  G_fincLvector< )  does  not^  Nomially.  the 
GRASS  programmer  need  not  wony  about  qualified  vs.  unqualified  names  since 
all  library  routines  handle  both  forms.  However,  if  the  programmer  wants  the 
name  to  be  returned  unqualified  (for  displaying  the  name  to  the  user,  or  storing  it 
in  a  data  file,  etc.),  then  G_fincLvectoi2( )  should  be  used. 

See  ^.7.1  Mapset  Search  Path  [p.20]  for  more  details  about  the  search  patJi. 

Be  warned  diat  G_find_vector2( )  should  not  be  used  directly  on  a  command  line 
argiunent,  since  modifying  argv(  ]  rx)t  be  valid.  The  argument  should  be  copied  to  another 
character  buffer  which  is  then  passed  to  G_find_vector2( ). 


find  a  vector  file 
find  a  vector  file 
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Fbr  example,  to  find  a  vector  file  anywhere  in  the  database: 

char  name[50]; 
char  *m^)eet; 


if  ((mapset  =  G_fintLvectDr(natne,'*”))  ==  NULL) 

/*  not  found  */ 

To  check  that  the  vector  file  exists  in  the  current  mapset: 
char  nanie[50]; 


if  (G_fin[LvectDr(name,G_mapeet( ))  =  =  NULL) 
/*  not  found  */ 


12.10.3.  OpenmganElTdstiiigVectior  File 

The  following  routine  opens  the  vector  file  name  in  ne|»et  for  reading. 

The  vector  file  name  and  nxqpset  can  be  obtained  interactively  using 
G_askjuector_old{p.  101)  or  Gj3skjxctorJnumpsetip.l0l)y  and  non-interactively 
using  GJindjuectorip.  102)  or  GJvndjoector2ip.  102). 

FILE  * 

G_Jopen_vecter_dd  ( name,  mapset)  open  an  existing  vector  fUe 

char  *name; 
char  *mapset; 

This  routine  opens  tiie  vector  file  name  in  mapset  for  reading. 

A  file  descriptor  is  returned  if  the  open  is  successful.  Otherwise  the  NULL 
pointer  is  returned  (no  diagnostic  message  is  printed). 

The  file  descriptor  can  then  be  used  with  routines  in  the  Dig  Library  to  read  the 
vector  file.  (S^  §23  Dig  Library  [p.  123].) 

Note.  This  routine  does  not  call  any  routines  in  the  Dig  Dbrary  ;  No 
initialization  of  the  vector  file  is  done  by  this  routine,  directly  or  indirectly. 
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12.10.4  Crating  and  OpomigN^  Vector 

The  following  routine  creates  tiie  new  vector  fUe  name  in  the  cunent  mapset?®  and 
opens  it  for  wiiting.  The  vector  file  name  should  be  obtained  interactively  using 
G_ask_vectx)r  jwuKp.  101).  If  obtained  non-interactively  (e.g.,  from  the  command  line), 
GJegalJilemrmip.72)  should  be  called  first  to  m^  sure  that  name  is  a  valid 
GRASS  file  name. 

Waning:  If  name  already  exists,  it  will  be  erased  and  re-created  empty.  The 
interactive  routine  G_psk_vector_/ieuip.  lOl)  guarantees  that  name  will  not  exist,  but  if 
name  is  obtained  from  the  command  line,  name  m^  exist  In  this  case 
GJmd_vector{p.l02)  could  be  used  to  see  if  name  exists. 


FILE  * 

G_fopen^vecfior_jiew  (name)  open  a  new  vector  file 

char  *name; 

Creates  and  opens  tiie  vector  file  name  for  writing. 

A  file  descriptor  is  returned  if  the  open  is  successful.  Otherwise  the  NULL 
pointer  is  returned  (no  diagnostic  message  is  printed). 

The  file  descriptor  can  then  be  used  with  routines  in  the  Dig  Library  to  write  the 
vector  file.  (S^  §i5  Dig  Library  [p.  123].) 

Note.  This  routine  does  not  call  any  routines  in  the  Dig  library.  No 
initialization  of  the  vector  file  is  done  by  this  routine,  directly  or  indirectly.  Also, 
only  the  vector  file  itself  (i.e.,  the  dig  file),  is  created.  None  of  the  other  vector 
si:5)port  files  are  created,  removed,  or  modified  in  any  way. 


12.10.5.  ReaAngand  Writing  Vectxx' Files 

Reading  and  writing  vector  files  is  handled  by  routines  in  the  Dig  Library.  See  §15 
Dig  Dbrary  \p.  123]  for  details. 


12.10.6.  Vectw  Category  File 

GRASS  vector  files  have  category  labels  associated  with  them.  The  category  file  is 
structured  so  that  each  category  in  the  vector  file  can  have  a  one-line  description 


GRASS  doeai’t  allow  files  to  be  cieatecl  outside  the  current  mapeet  See  §4.7  Database 
Access  Rides  \p  20i. 
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The  routines  described  below  read  and  write  the  vector  categoiy  file.  Th^  use  the 
Categories  structure  which  is  described  in  ^12.17  GIS  Library  Data  Structures  \p.  118]. 

Note:  The  vector  cat^oiy  file  has  exactly  the  same  structure  as  die  cell  cab^iy  file. 
In  fact  it  exists  so  that  the  program  vect.to.ceU  can  convert  a  vector  file  to  a  c^  file 
that  has  an  iq>-to-dale  categoiy  file. 

The  routines  described  in  ^12.92.2  Querying  and  Changing  the  Categories  Structure 
ip.se]  which  modify  the  Categories  structure  can  therefore  be  used  to  set  and  change 
vector  categories  as  well. 

Gjnead_vector_cals  (name,  mapset,  cats)  read  vector  category  file 

char  *name; 

char  *mapset; 

struct  Categories  *cats; 

The  categoiy  file  for  vector  file  name  in  nx9»et  is  read  into  die  cats  structure. 

If  there  is  an  error  reading  the  cat^oiy  file,  a  diagnostic  message  is  printed  and 
-1  is  returned.  Otherwise,  0  is  returned. 

G_write_vector_cats  (name,  cats)  write  vector  category  file 

char  *name; 

stnict  Categories  *cats; 

Writes  the  categoiy  file  for  the  vector  file  name  in  the  cuirent  mapset  from  the 
cats  structure. 

Returns  0  if  successful.  Otherwise,  -1  is  returned  (no  diagnostic  is  printed). 


12.11.  ^te  List  Rxxsessii^ 

GRASS  has  a  point  database  capabilitify  called  sites,  which  manages  a  database  of 
point  or  site  information  The  sites  program  provides  the  m^ority  of  the  analytical 
capabilities  within  GRASS  for  site  data  The  routines  described  here  provide 
programmers  with  mechanisms  for  reading  existing  site  list  files  and  for  creating  new 
ones.  The  reader  should  also  see  §7  Point  Data:  Ste  List  Files  \p.39]  for  more  details 
about  the  site  list  files. 
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12.11.1.  Rmydiig  for  She  List  FDes 

The  followii^g  iDutines  interactively  pron^pt  tiie  user  for  a  site  list  file  name.  In  each, 
the  prompt  string  will  be  printed  as  the  first  line  of  the  full  prompt  which  asks  the 
user  to  enter  a  site  list  file  name.  If  pronyit  is  die  empty  strung  ""  then  an  appropriate 
prompt  will  be  siirstituted.  The  name  diat  the  user  enters  is  copied  into  the  name 
buffer.^^  These  routines  have  a  built-in  ’list?  capability  which  allows  tiie  user  to  get  a 
list  of  existing  site  list  files. 

The  user  is  required  to  enter  a  valid  site  list  file  name,  or  else  hit  the  RETURN  key  to 
cancel  the  request  If  the  user  enters  an  invalid  response,  a  message  is  printed,  and  the 
user  is  prompted  again  If  the  user  cancels  the  request,  the  NOLL  pointer  is  returned. 
Otherwise  the  mapset  where  die  site  list  file  lives  or  is  to  be  created  is  returned.  Both 
the  name  and  the  mapset  are  used  in  other  roirines  to  refer  to  the  site  list  file. 

char  * 

G_a8kjsitea_old  (prompt,  name)  pronpt  for  existing  ^  list  fUe 

char  *prompt; 
char  *name; 

the  user  to  enter  the  name  of  an  existing  site  list  file  in  any  mapset  in  the 
database. 


char  * 

G_askjsiteSLilI_nMp8et  (pronpt,  name)  pronp:  for  easting  site  list  fUe 

char  *prompt; 
cliar  *name; 

Asks  the  user  to  enter  the  name  of  an  existing  site  list  file  in  the  current  mapset 

char 

G_a8k_sitesjiew  ( prompt  name)  ponpt  for  new  site  list  file 

char  ^prompt 
char  *name; 

Asks  the  user  to  enter  a  name  for  a  site  list  file  which  does  not  exist  in  the 
current  mapset 

Here  is  an  example  of  how  to  use  these  routines.  Note  that  the  programmer  must 
handle  the  NULL  return  properly: 


TTie  size  of  name  should  be  large  enough  to  hold  any  GRASS  file  name.  Most  systems 
allow  file  names  to  be  quite  long.  It  is  recommended  that  name  be  declared  char  namefSOf. 
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char  *mBpset; 
char  nanie[50J; 

mepset  =  G_ask^ates_olH("£kiter  ate  list  hie  to  be  pRKressed”,  name); 
if  (mapset  ==  NULL) 
exitiO); 


12.11.2.  Opening  Site  List  Files 

The  following  routines  open  site  list  files: 

FILE  * 

G_f<^jenjsitesjnew  ( name)  open  a  new  site  list  file 

char  *name; 

Creates  an  empty  site  list  file  name  in  the  current  mapset  and  opens  it  for 
writing. 

Returns  an  open  file  descriptor  if  successful.  Otherwise,  returns  NULL 


FILE  * 

G_fo|jenjsites_<Jd  ( name,  mapset)  open  an  existing  site  list  file 

char  *natne; 
char  *mapset; 

Opens  the  site  list  file  name  in  mapset  for  reading. 

Returns  an  open  file  descriptor  if  successful.  Otherwise,  returns  NULL 


12.11.3.  Rearfir^  and  Writing  She  List  Files 

G_get_sile  (fd,  east,  north,  desc)  read  site  list  file 

FlLE*fd; 

dodble  *east,  ''Tiorth; 
char  '=*desc; 

This  routine  sets  east  and  north  for  the  next  "point"  from  the  site  list  file  open 
on  file  descriptor  fd  (as  returned  by  GJbperi_sites_olcl{p.  107)),  and  desc  is  set  to 
point  to  the  description  of  the  site. 

ftetums:  1  got  a  site;  -1  no  mons  sites. 

For  example: 
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dovdble  east,  north; 
char  *de8c; 

FlLE*fd; 

fd  =  G_fopen_site_old  (narre,  rmpsetY, 

while  (G_get_ate  (fd,  &east,  fenorth,  &desc)  >  0) 

printf  ("%lf  %lf  %s\n",  east,  norfli,  deac); 

Note;  desc  points  to  static  memoiy,  so  each  call  overrides  the  description  from 
the  previous  call. 

G_putjsile  (fd,  east,  nordi,  desc)  mite  site  list  fUe 

FILE*fd; 
double  east,  north; 
char  *desc; 

Writes  the  east  and  north  coordinates  and  site  description  desc  to  the  site  file 
opened  on  file  descriptor  fd  (as  returned  by  G_^pen_sites_neuXp.i07)). 


12.12.  Temporary  FQes 

Often  it  is  necessary  for  programs  to  use  temporary  files  to  store  information  that  is 
only  useful  durmg  the  program  run  After  the  program  finishes,  the  information  in  the 
terrporary  file  is  no  lorrger  needed  and  the  file  is  removed  (Dommonly  it  is  required 
that  temporary  file  names  be  unique  from  iirvocation  to  invocation  of  the  program  It 
would  rx)t  be  good  for  a  fixed  narr£  like  "/tmp/rrrytempfile"  to  be  used.  If  the  program 
were  run  by  two  users  at  the  same  time,  they  wordd  use  the  same  terrporary  file. 

The  following  routine  generates  temporary  file  names  which  are  unique  within  the 
program  arxi  across  all  GRASS  programs. 

char  ^ 

G_teni]file  (  )  letwTTS  a  terrpoixay  fUe  name 

This  routine  returns  a  pointer  to  a  string  contauing  a  unique  file  name  that  can  be 
used  as  a  temporary  file  within  die  program  Successive  calls  to  G_tempfile( ) 
will  generate  new  names. 

Only  the  file  name  is  generated.  The  file  itself  is  not  created.  To  create  the  file, 
the  program  must  use  standard  UNIX  functions  which  create  and  open  files,  e.g., 
creatf  )  or  fopen( ). 

The  programmer  should  take  reaionable  care  to  remove  (unUnk)  the  file  before 
the  program  exits.  Ifowever,  GRASS  database  management  will  eventually 
remove  all  temporaiy  files  created  by  G_tempfile( )  that  have  been  left  behind  by 
the  programs  which  created  them 
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Nbta  The  teii^raiy  files  sae  created  in  die  GRASS  database  rather  than  under  /trap. 
This  is  done  for  two  reasons.  The  hist  is  to  increase  the  likelihood  that  enou^  disk  is 
available  for  laige  temporaiy  files  ance  Amp  may  be  a  veiy  small  file  system.  The 
second  is  so  diat  abandoned  temporaiy  files  can  be  automatically  removed  (but  see  the 
warning  below). 

Waniiig.  The  temporary  files  are  named,  in  part,  using  the  process  id  of  the  program. 
GRASS  database  management  will  remove  these  files  only  if  the  program  which 
created  them  is  no  longer  running.  However,  this  feature  has  a  subtle  trap.  Programs 
which  create  child  processes  (using  the  UNIX  forkf  routine)  should  let  the  child 
call  G_tempfile( ).  If  the  parent  does  it  and  then  exits,  die  child  may  find  that  GRASS 
has  removed  the  tenporaiy  file  since  the  process  which  created  it  is  no  longer  running. 


12.13.  Cotnmand  Line  PEirsaig 

The  following  two  routines  provide  a  mechanism  for  command  line  parsing.  Use  of 
these  routines  will  standardize  GRASS  commands  that  expect  command  line 
aiguments. 

The  routines  are  described  first,  followed  by  a  short  example  (on  page  112)  of  their 
usage. 

G_p0r9e_con»nand  (argc,  argv,  keys,  stash)  parse  corrrmnd  line 

int  aigc; 
char  *argv[  ]; 

struct  CommancLkeys  *keys; 
int  (*stash)( ); 

This  routine  parses  command  lines  in  any  of  the  following  formats: 

command  value  1  value2  voLue3  vcdue4 

the  options  are  in  the  correct  positions 

command  ualuel  -  -  vcdue4 

the  options  are  in  the  correct  positions,  where  minuses  (-)  are 
interpreted  as  "accept  the  default  for  this  position" 

command  opt2=ualue2  opt4  valued  opt3=valiie3  optl=ualuel 

the  options  are  in  mixed  order,  but  the  correct  position  is 
ascertained  by  looking  for  the  "opt"  string  in  the  keys  structure, 
which  contains  the  "correct"  position  for  the  option. 

command  value  1  -  opt4=value4 

a  mixed  form  of  the  above  formats 

■'2  See  alao  GJbrkip  lie). 
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llie  command  line  parametEis  argv  and  the  number  of  parameters  argc  from  the 
main( )  routine  are  passed  directly  to  G_parse^oTnrmnd(. ). 

The  option  names  and  poations  are  specified  in  keys^  which  is  an  anay  of 
Conmmdjieys  structures,  defined  as; 

struct  CoimiancLkeys 

{ 

char ’"alias; 
int  position; 


The  keys  array  is  teiminated  by  a  NULL  alias .  For  example: 

struct  CommBndLkeys  keysl  ]  = 

{ 

{"name",  1}, 

{"color’,  2}, 

{NULL,0} 

}; 


Once  a  position  is  deteimined,  either  by  actual  position  or  by  deduction,  the 
position  number  and  option  value  are  sent  to  the  specified  routine  stash( ),  which 
should  "stash"  tiie  information  somewhere  for  later  use  by  the  program  This 
routine  must  be  defined  as: 

stash  (position,  value) 
int  position; 
char  *value; 

and  return  0  if  the  vsdue  is  valid,  1  otherwise. 

G_parse_comrmnd  ( )  returns  the  following  codes: 

1  There  are  no  aiguments  on  the  command  line,  or  the  first 
at]gument  is  the  word  "help"  (a  usage  message  is  printed  for  the 
user), 

0  There  were  no  errois  on  the  command  line.  (This  doesn’ t  imply 
that  all  parameters  were  specified,  just  that  those  specified  were 
valid). 

<  0  There  are  errors  on  the  command  line  (nothing  is  printed  for  the 
user). 
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G_pQKSe_OQnii]end_Usage  (program,  foima^  commnd  line  usage  mssage 

char  *prograin; 

struct  ConrrwitLkeys  *fceys; 

int  foimat; 

This  routine  prints  a  standard  usage  message  for  the  program  (usually  aigv[0]) 
based  on  the  options  described  in  die  parameter  (which  is  the  same  as  that 
passed  to  G_parse_conmindip.  109)).  The  fermat  of  the  message  may  either  be 
USAGILSHORT  for  a  tase  fonnat,  or  USAGELLONG  for  a  longer  format 
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FbMmpie.  Tt^  following  exanqple  parses  a  command  which  expects  two  arguments:  a 
mme ,  and  a  color : 

♦include  "gisii" 

struct  CoirmnancLkeyB  keyst  ]  = 

{ 

{"nanne",  1}, 

{"coloi^’,  2}, 

{NULL,0} 


static  char  name[50]; 
static  char  color[50]; 
static  int  have_nanie  =  0; 
static  int  have_color  =  0; 

static 

stashtpoation,  value) 
int  position; 
char  *value; 

{ 

switch  (position) 

{ 

case  1; 

strcpy  (name,  value); 
have_name  =  1; 
return  0; 
case  2; 

strcpy  (color,  value); 
have_color  =  1; 
rettm  0; 

} 

return  1; 

} 

main  (argc,  argv)  char  *argv[  ]; 

{ 

int  stat; 

G_gisinit  (argvfO)); 

stat  =  G_parse_command  (aiijc,  argv,  keys,  sta^; 
if  (stat  !=  0  II  !have_name  ||  !have_color) 

{ 

if  (stat  <=  0) 

G_parge_commandLusage  (argvfO],  keys,  USAGE_LONG); 
exitd); 

} 

parsing  conrplete.  proceed  to  function  iin(dementation  */ 
exittO); 

} 
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12.14  String  Mampulatkii  F\in^ 

This  section  describes  some  routines  which  peifoim  string  manipulation  Stririgs  have 
the  usual  C  meaning:  a  NULL  terminated  array  of  characters. 

These  next  3  routines  copy  characters  from  one  string  to  another, 
char  * 

G_s<rq]y  (dst,  src)  copy  strings 

char  *dst,  *src; 

Copies  the  src  strii^  to  dst  iq)  to  and  including  the  NULL  which  teminales  the 
src  string.  Returns  fist 

char  * 

G_stmcpy  (dst;  src,  n)  copy  stiirtgs 

char  *dst,  *src; 
intn; 

Copies  at  most  n  characters  from  the  src  string  to  dst  If  src  contains  less  than  n 
characters,  then  only  those  characters  are  copied.  A  NULL  byte  is  added  at  the 
end  of  dst  This  implies  that  dst  should  be  at  least  nf  1  bytes,  long.  Returns  dst 

Note.  This  routine  varies  from  the  UNIX  stmcpyf )  in  that  G_stmcpy( )  ensures 
that  dst  is  NULL  tenninated,  while  stmcpyf )  does  not 

char* 

G_strcat  (dst  src)  concatentate  sbings 

char  *dst  *src; 

Appends  the  src  string  to  the  end  of  the  dst  string,  which  is  then  NULL 
terminated.  Returns  dst 

These  next  2  routines  remove  unwanted  white  space  from  a  single  string, 
char  * 

G_S(Iueeze  ( s)  remove  unnecessary  iJute  space 

char  *s; 

Leading  and  trailing  white  space  is  removed  from  the  string  sand  internal  white 
space  which  is  more  than  one  character  is  reduced  to  a  single  space  character. 
White  space  here  means  spaces,  tabs,  linefeeds,  newlines,  and  formfeeds.  Returns 

SL 
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Gjstrip  (s)  rerrvve  Uading/trairujig  uMe  space 

char  *s; 

Leading  and  trailiiig  white  space  is  removed  from  the  string  s.  White  space  here 
means  only  spaces  and  tabs.  There  is  no  return  value. 

This  next  routine  copies  a  string  to  allocated  memory. 

char* 

G_sliOre  (s)  copy  string  to  allocated  memory 

This  routine  allocates  enough  memory  to  hold  the  string  s*  copies  s  to  the 
allocated  memory,  and  returns  a  pointer  to  the  allocated  memory. 

These  2  routines  convert  between  upper  and  lower  case. 

G_tcd[case  ( s)  convert  string  to  lower  case 

char  *s; 

Upper  case  letters  in  the  string  s  are  converted  to  their  lower  case  equivalenL 
Returns  s. 

G_taucase  ( s)  convert  string  to  upper  case 

char  *s; 

Lower  case  letters  in  the  string  s  are  converted  to  their  i5)per  case  equivalenL 
Returns  & 

And  finally  a  routine  which  gives  a  printable  version  of  control  characters, 
char  * 

G_unctri  (c)  printable  version  of  control  character 

unsigned  char  c; 

This  routine  returns  a  pointer  to  a  string  which  contains  an  Elnglish-like 
representation  for  the  character  c.  This  is  useful  for  non-printirig  characters,  such 
as  control  characters.  Control  characters  are  represented  by  ctii-c,  e.g.,  control  A 
is  represented  by  Ctrl -A.  0177  is  represented  by  DEL/RUB.  Normal  characters 
remain  unchanged. 

This  routine  is  useful  in  combii’ution  with  GJ.ntr_charip.117)  for  printing  the 
user' s  intemqrt  character: 
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char  GJntr_char( ); 
char  *GLiinctri(); 

piintfC'Your  interrupt  character  is  %s\n",  G_unctri(G_inlr_char( ))); 


Note.  G_unctii( )  uses  a  hidden  static  buffer  which  is  overwritten  from  call  to 
call. 


12.15.  E^nhanoed  UNIX  Routmes 

A  number  of  useful  UNIX  library  routines  have  side  effects  which  are  sometimes 
undesirable.  The  routines  here  provide  the  same  functions  as  their  corresponding  UNIX 
routine,  but  with  different  side  effects. 


12.15.1.  Runniiig  in  the  Background 

The  standard  UNIX  foik( )  routine  creates  a  child  process  which  is  a  copy  of 
parent  process.  The  fordd )  routine  is  useful  for  placiiig  a  program  into 
background.  For  example,  a  program  ttiat  gathers  input  from  the  user  interactively, 
knows  that  the  processing  will  take  a  long  time,  might  want  to  run  in  the  background 
after  gathering  all  the  input  It  would  fork( )  to  create  a  child  process,  the  parent  would 
exit; )  allowing  the  child  to  continue  in  the  background,  and  the  user  could  then  do 
other  processiug. 

However,  there  is  a  subtle  problem  with  this  logic.  The  foik( )  routine  does  not  protect 
child  processes  from  keyboard  interrupts  even  if  the  parent  is  no  loriger  running. 
Keyboard  intemqrts  will  also  kill  background  processes  that  don’ t  protect 
themselves.^  Thus  a  program  which  puts  itself  in  the  background  may  never  finish  if 
the  user  intem^rts  another  program  which  is  running  at  the  keyboard. 

The  solution  is  to  foik( )  but  also  put  the  child  process  in  a  process  groiq)  which  is 
different  from  the  keyboard  process  group.  G_foik( )  does  this. 


RDgrammers  who  use  /bin/sh  know  tliat  programs  run  in  the  background  (uang  &  on  the 
command  line)  are  not  automatically  protected  from  keyboard  interrupts.  To  protect  a 
command  that  is  run  in  the  background,  /bin/sh  users  must  do  nohip  conrmnd&.. 
Rngranmeis  who  use  the  /bin/csh  (or  other  variants)  do  not  know,  or  foiiget  that  the  Gshell 
automatically  protects  background  processes  from  keybo.-wd  interrupts. 
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GJcricO  create  a  protected  child  process 

This  routine  creates  a  child  process  by  calling  the  UNIX  foik( )  routine.  It  also 
changes  the  process  groiq)  for  die  child  so  that  intentQ)ts  from  the  keyboard  do 
not  reach  the  child.  It  does  not  cause  the  parent  to  eadt( ). 

GJbrid  )  returns  what  forid )  returns:  -1  if  forid )  failed;  otherwise  0  to  the  child, 
and  the  process  id  of  the  new  child  to  the  parent 

Note.  Interrupts  are  still  active  for  the  child.  IntemQ)ts  sent  using  the  kill 
command,  for  example,  will  internet  die  child.  It  is  supply  diat  keyboard- 
generated  intempts  are  not  sent  to  the  child. 


12.15.2.  PartiaUy  IntemptiUe  Sljistem  Call 

The  UNIX  ^stem( )  call  allows  one  program,  the  parent,  to  execute  another  UNIX 
command  or  program  as  a  child  process,  wait  for  that  process  to  complete,  and  then 
continue.  The  problem  addressed  here  concerns  intempts.  During  die  standard 
systend )  call,  the  child  process  inherits  its  re^nses  to  intempts  from  the  parent 
This  means  diat  if  the  parent  is  ignoring  intempts,  the  child  will  ignore  them  as  well. 
If  the  parent  is  terminated  by  an  intempt,  the  child  will  be  also. 

However,  in  some  cases,  this  may  not  be  the  desired  effect  In  a  menu  environment 
where  the  parent  activates  menu  choices  by  running  commands  using  die  system! ) 
call,  it  would  be  nice  if  the  user  could  intempt  the  command,  but  not  terminate  the 
menu  program  itself.  The  G_s!ystem( )  call  allows  this. 

G_Siysteni  (command)  run  a  shell  level  command 

The  shell  level  omnmand  is  executed.  Intempt  signals  for  the  parent  program  are 
ignored  during  the  call.  Intempt  signals  for  de  ooranaDtid  are  envied.  The 
intempt  signals  for  the  parent  are  restored  to  dieir  previous  settings  ipon  retura 

G_^stem( )  returns  the  same  value  as  system! ),  which  is  essentially  the  exit 
status  of  the  ocHnmand  See  UNIX  manual  ^stemd)  for  details. 


12.16.  Misc€Uaneous 

A  number  of  general  purpose  routines  have  been  provided. 


§12GIS  Ubrary 


-  117- 


-  117- 


char  * 

G_date()  current  and  time 

Returns  a  pointer  to  a  string  ^/sinch  is  the  current  date  and  time.  The  format  is 
the  same  as  that  produced  by  the  UNIX  date  command. 

G  gets  (buf)  get  a  line  of  input  (detect  ctri-z) 

char  *buf; 

This  routine  does  a  gets  ( )  from  stdin  into  but  It  exits  if  end-of-file  is  detected. 
If  stdin  is  a  tty  (i.e.,  not  a  pipe  or  redirected)  then  ctri-z  is  detected. 

Returns  1  if  the  read  was  successful,  or  0  if  ctii-z  was  entered. 

Note.  This  is  very  useful  for  allowing  a  program  to  reprompt  when  a  program  is 
restarted  after  being  stopped  with  a  ctd-z.  If  this  routine  returns  0,  then  the 
calling  program  should  re-print  a  prompt  and  call  G_gets  ( )  again.  For  example: 

char  buff 1024]; 
do  { 

printfC'EntBr  aome  input:  ")  ; 

}  while  (  !  G_gets(buf)  )  ; 


char  * 

G_ho«ne  ( )  user’s  home  duectory 

Returns  a  pointer  to  a  string  which  is  die  full  path  name  of  the  iBer's  home 
directory. 


char 

G _intr_char  (  )  return  interrupt  char 

This  routine  returns  the  user^  s  keyboard  internet  character.  This  is  the  character 
that  generates  the  SIGINT  signal  from  the  keyboard. 

See  also  G_unctrl{p.  114)  for  converting  this  character  to  a  printable  format 

G_percent  (n,  total,  incr)  print  percent  corrplete  messages 

int  n; 
int  total; 
int  incr. 

This  routine  prints  a  percentage  complete  message  to  stderr.  The  percentage 
complete  is  (n/  total)*  100,  arxl  these  are  printed  only  for  each  incr  percentage. 
This  is  perhaps  best  explained  by  example; 
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#include  <8tiiio.h> 

introw; 

intnrows; 
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mows  =  1352;  /*  1352  is  not  a  q)ecial  value  -  exanple  only  */ 
fprintf  (stdeir,  "Itercmit  conplete: "); 
for  (row  =  0;  row  <  mows;  row-H-) 

G_percent  (row,  mows,  10); 

This  will  print  connpletion  messages  at  10^  increments;  i.e.,  10%,  20%,  30%, 
etc.,  up  to  100%.  Each  message  does  not  appear  on  a  new  line,  but  rather  erases 
the  previous  message.  After  100%,  a  new  line  is  printed. 

char* 

G_progranLJiaine  ( )  return  program  name 

This  routine  returns  the  name  of  the  program  as  set  by  the  call  to  G_gisinUip.64). 

char* 

G_wilOEIIli  ( )  user’s  name 

Returns  a  pointer  to  a  string  which  is  the  user' s  login  name. 

G_yes  (question,  default)  ask  a  yes/no  question 

char  *questiori; 
int  default; 

This  routine  prints  a  question  to  the  user,  and  expects  the  user  to  respond  either 
yes  or  no.  (Invalid  responses  are  rejected  and  the  process  is  repeated  until  the 
user  answers  yes  or  no.) 

The  default  indicates  what  the  RETURN  key  alone  should  mean  A  defiEodt  of  1 
indicates  that  RETURN  means  yes,  0  indicates  that  RETURN  means  no,  and  -1 
indicates  that  RETURN  alone  is  not  a  valid  response. 

The  question  will  be  appended  with  "(y/n)  ",  arxl,  if  default  is  not  -1,  with  "[y]  " 
or  "[n]  ",  depending  on  the  default 

G_yes  ( )  returns  1  if  the  user  said  yes,  and  0  if  the  user  said  no. 


12.17.  GIS  Libraiy  Data  StxxKtu^ 

Some  of  the  data  structures,  defined  in  the  "gis.h"  header  file  and  used  by.routines  in 
this  Ubraty,  are  described  in  the  sectioris  below. 
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12.17.1.  struct  CdLhfad 

The  cell  header  data  structure  is  used  for  two  purposes.  It  is  used  for  cell  header 
information  for  map  layais.  It  also  used  to  hold  window  values.  The  structure  is: 

struct  CelLhead 
{ 


intfoimat; 

/* 

nunnber  of  bytes  per  cell 

*/ 

int  connpessed; 

/* 

comfaessedd)  or  not  coiiixessedIO) 

*/ 

int  rows,  cols; 

f* 

nuitiier  of  rows  and  columns 

*1 

int  proj; 

1* 

projection 

*/ 

int2»ne; 

/* 

zone 

*! 

double  ew_res; 

1* 

east- west  resolution 

*! 

double  na_res; 

I* 

north-south  resolution 

*/ 

double  nordi; 

/* 

northern  edge 

*/ 

double  south; 

/* 

southern  edge 

*/ 

double  east; 

/* 

eastern  edge 

*/ 

double  west; 

/* 

western  edge 

*/ 

}; 

The  format  and  corrpressed  fields  apply  only  to  cell  headers.  The  format  field 
describes  the  number  of  bytes  per  cell  data  value  and  the  compressed  field  indicates  if 
the  cell  file  is  corrpressed  or  not  The  other  fields  apply  both  to  cell  headers  and 
windows.  The  geogra|diic  boundaries  are  described  by  north,  south,  east  and  west. 
The  grid  resolution  is  described  by  ew_res  and  ns_res.  The  cartographic  projection  is 
described  by  proj  and  the  related  zone  for  the  projection  by  zone.  The  rous  and  cols 
indicate  the  nuntoCT  of  rows  and  columns  in  cell  file,  or  in  the  window.  See  §5.5 
Cell  Header  Format  \p.26\  for  more  information  about  cell  headers,  and  §9.i  Window 
\p.47\  for  more  information  about  windows. 

The  routines  described  in  ^12.9.1  Cell  Header  FUe  lp.89]  use  this  structure. 


12.17.2.  struct  Categories 

The  category  data  structure  contains  map  layer  title  and  category  labels.  It  is  used  both 
for  cell  files  and  vector  files.  The  structure  is: 


§12  CIS  Library 


-120- 


-  120- 


struct  Categories 
{ 


C^ElLnuin; 

/* 

total  number  of  eateries 

*/ 

char 

/* 

name  of  data  layer 

*/ 

char 

!* 

printf-like  format  to  gaierate  labels 

*! 

float  ml; 

/* 

multiplicarion  coefficient  1 

*! 

float  al; 

/* 

addition  co^cient  1 

*! 

float  m2; 

/* 

nultiidication  coefficient  2 

*/ 

float  a2; 
struct  Cat_list 

{ 

CELL  num; 

/* 

addition  co^cient  2 

*/ 

/* 

cata^riy  nutiber 

*! 

char  *label; 

} 

/* 

category  label 

*/ 

int  count; 

/* 

number  of  Idoels  allocated 

}; 

The  Categories  stmctute  contains  a  tide  for  the  map  layer,  the  largest  category  in  the 
layer  (nurni,  an  automatic  label  generation  rule  for  missing  labels  {frnt,  ml,  al, 
m2,  a2),  and  a  list  of  cat^oiy  labels  for  count  specific  cat^ories. 

This  structLire  should  be  accessed  using  the  routines  described  in  ^12.9.2  Cell  Category 
File  \p.91]. 


12.17.3.  struct  Colors 

The  color  data  structure  holds  red,  green,  and  blue  color  intensities  for  cell  cathodes. 
The  structure  is: 

struct  Colors 
{ 


CELL  tiitynax; 

/* 

nin/nax  color  numbers 

■"/ 

uchar  *red; 

/* 

red,  green,  blue  (0-255) 

*/ 

uchar  ’"gm; 

/* 

allocated  as  needed 

♦/ 

uchar  ’"blu; 
uchar  r0,g0,b0; 

red,  green,  blue  for  cat  0 

*/ 

}; 

Except  for  category  zero,  the  color  intensities  are  stored  in  the  (unsigned  char)  arrays 
red,  gm,  and  bUi.  The  minimum  and  maximum  categories  which  have  colors  are  rrin 
and  max. 

The  routines  described  in  ^12.9.3  Cell  Color  Thble  \p.94\  use  this  structure. 

The  routine  G^et_colorip.95)  should  be  used  to  get  individual  colors  from  the 
structure.  However,  for  completeness,  to  find  the  colors  for  category  n: 
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if  (n  !=  0  &&  n  >=  nnin  &&  n  <=  max) 
{ 

red[n-min| 

gm[n-nin] 

blu[n-n»n] 

} 


The  color  for  cafc^oiy  zero  is  represented  by  rO,  gO  and  bO. 


12.17.4.  struct  Histoiy 

The  History  structure  is  used  to  document  cell  files.  The  information  contained  here 
is  for  the  user.  It  is  not  used  in  any  operational  way  by  GRASS  The  structure  is: 

#define  MAXEDLINES  25 
♦define  REXHORD_LEN  80 

atnict  Hstoiy 

{ 

char  niB?)idrRBCORD_LEI^; 
char  title[IlEXXDRD_LEN]; 
char  nie4)aetfREXX)RD_Ii^; 
char  crealDr(REXX)RD_LEN]; 
char  maptype[REXX)RD_LE]N]; 
char  clalsrc_l(REXX)RD_LENl; 
char  clatsrc_2(TlBOORD_LEN]; 
char  kBywrd[RBCXDRD_LEN]; 
int  edlinecnt; 

charedhistnviAXEDlJNES][RBroRD_I^ 

}; 


The  mapid  and  mapset  are  the  cell  file  name  and  mapset,  title  is  the  ceU  file  title, 
creator  is  the  user  who  created  the  file,  maptype  is  die  map  type  (which  should 
always  be  "cell"),  datasrcj.  and  datasrc_2  describe  the  original  data  source,  heyiurd 
is  a  one-line  data  description  and  edhist  contains  edUnecrrt  lines  of  user  comments. 

The  routines  described  in  ^12.9.4  Cell  Hstory  File  [p.SiS]  use  this  structure.  However, 
there  is  very  little  support  for  manipulating  the  contents  of  this  structure.  The 
progTEonmer  must  manipulate  the  contents  directly. 

Note  Some  of  the  information  in  this  structure  is  not  meaningful.  For  example,  if  the 
cell  file  is  renamed,  or  copied  into  another  mapset,  the  rrvpid  and  rmpset  will  no 
longer  be  correct  Also  the  title  does  not  reflect  the  true  cell  file  title.  The  true  tide  is 
maintained  in  the  category  file. 

Wandi«  This  structure  has  remained  unchanged  since  the  inception  of  GRASS. 
There  is  a  good  po.ssibility  that  it  will  be  changed  or  eliminated  in  future  releases. 
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12.17^  struct  Range 

The  Range  stnicture  contains  the  minimum  and  maorimiifn  values  which  occur  in  a  cell 
file.  The  structure  is: 

struct  Range 

{ 


CELL  nrnin; 

nin  negative 

*/ 

CELL  nrnax; 

/* 

max  negative 

*/ 

CELL  pnin; 

/* 

ninpoative 

*! 

CELL  pmax; 

max  poeivive 

*! 

}; 

Note  that  the  range  is  divided  into  positive  and  negative  ranges.  TIk  positive  rar^e  is 
represented  by  pnin  and  pmax,  and  the  n^ative  range  by  rmin  and  wmx.  If  there 
are  no  negative  values  in  the  cell  file,  then  both  nrrin  and  ramx  will  be  zero.  Also  if 
there  are  no  positive  values  in  the  file,  tlien  both  pnin  anl  pmax  will  be  zero. 

The  following  idiomatic  expression  is  used  to  detenrdne  tte  full  data  rar^e: 

nin  =  nmin  ?  nnin  :  pnin  ; 
n»x  =  (xnax  ?  pmax  :  nmax  ; 

The  routines  described  in  §12.9.5  Cell  Range  File  !p.99]  use  tiis  structure. 


12.18.  Ixiadiiig  tfae  GIS  library 

The  library  is  loaded  by  specifying  $(GISLIB)  in  tte  Gnakefile.  The  foUowirg 
example  is  a  conoplete  Gmak^e  which  compiles  code  that  uses  this  library: 

_ Gimkefile  for  .ti(aTST.Tm _ 

OBJ  =  maiao  subl.o  sub2.o 

pgm:  $(OBJ)  $(GISLIB) 

$(CQ  $(IJ)FLAGS)  -o  $@  $(OBJ)  $(GISLIB) 

$(GISLJB):  *  in  case  the  library  changes _ 


See  §11  ConpiUng  GRASS  Programs  Using  Gmake  Ip.  551  for  a  complete  discussion  of 
Gmakefiles. 
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ChapbBclS 

Dig  Library 


13.1.  IntixiductiQn 

The  Dig  Ubrary  provides  the  GRASS  prograanmer  with  routines  to  process  the  binaay 
dig  vector  files.  It  is  assumed  that  the  reader  has  read  Database  Structure  |p.  15] 
for  a  general  description  of  GRASS  databases,  and  §d  Vector  Akqps  (p.3il  for  details 
about  vector  files  in  GRASS. 

The  routines  in  the  Dig  library  are  presented  in  functional  groupings,  rather  than  in 
alphabetical  order.  The  order  of  presentation  will,  it  is  hoped,  provide  a  better 
undetstanding  of  how  the  library  is  to  be  used,  as  well  as  show  the  inter-relationslups 
among  the  various  routines.  Note  diat  a  good  way  to  understand  how  to  use 
routines  is  to  look  at  toe  source  code  for  GRASS  programs  which  use  them.^ 

Note.  All  routines  and  global  variables  in  tons  library,  documented  or  undocumented, 
start  with  the  prefix  dlg_.^  To  avoid  name  conflicts,  programmers  should  not  create 
variables  or  routines  in  their  own  programs  which'use  tins  prefix. 

An  alphabetic  index  is  provided  in  ^24.5  Appendix  D.  Index  to  Dig  Library  \p.243]. 


13.1.1.  Indude  Files 

The  following  files  contain  definitions  and  structures  required  by  some  of  the  routines 
in  this  library.  The  programmer  should  therefore  include  these  files  in  code  that  uses 
this  library:^ 

’  Some  of  these  pnogrEms  are  a.b.vect,  b.a.vect,  vect.to.cell,  Dvect,  Gpoly,  Pimp,  and 
Vpatch. 

Warning  Tbere  are  also  6  additional  ^obal  varirfjles  and/or  routines  which  do  NOT 
begin  with  this  prefix;  debugf,  head,  sarrplejthresh,  linesJn^krmry,  MkmJjineJhr,  and 
Mern.cwr_position. 

TTie  GRASS  compilation  process,  described  in  §fi  CorrpUing  GRASS  Prograrrs  Usirig 
Grtnlr  ip  5.i| ,  autoirtitically  tells  the  C  compiler  how  to  find  this  and  other  GRASS  header  files. 
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#  include  "dig_defineah” 
#include  "dig_strticlB.h" 


13.1.2.  Vector  Arc  Types 

A  complete  discussion  of  GRASS  vector  tenxnnology  can  be  found  in  §6.1  What  is  a 
Vector  Map  Layer?  (p.32]  and  the  reader  should  review  that  section.  Briefly,  vector 
data  is  stored  as  arcs  representing  linear,  area,  or  point*  features.  These  arc  types  are 
coded  as  LINE,  AREA,  and  DOT  respectively,  (and  are  #defined  in  the  file 
"dig_defines.h"). 

13.1.3.  Levds  of  Access 

There  are  two  levels  of  read  access  to  these  vector  files: 

Level  One  provides  simple  access  to  the  arc  infonnation  contained  in  the  vector  files. 
There  is  no  access  to  cat^oiy  or  topology  infoimation  at  this  level. 

Level  Tho  provides  full  access  to  all  the  infonnation  contained  in  the  vector  file  and 
its  siq)port  files,  including  line,  cat^oiy,  node,  and  area  information.  This  level 
requires  more  from  the  programmer,  more  memoiy,  and  longer  startup  time. 

Note.  The  routines  in  this  library  which  process  arcs  are  named  usir^g  the  word  line. 
They  should  be  rramed  usirg  the  word  arc  instead.  Shxe  that  would  require  modifying 
a  lot  of  existing  code,  the  names  have  r»t  been  changed. 


13.2.  Levd  One  Read  Access 

Level  One  access  allows  the  reading  of  arcs  from  a  vector  file.  Most  of  the  routines 
require  a  file  descriptor  fd  open  to  read  a  vector  file,  as  returned  by 
G  Jbpen_vector_old{p.  103). 


13.2.1.  Initializad«VTernination 

The  following  routines  perform  initialization  and  termination  actions  for  Level  One 


Fbint  data  in  vector  files  is  not  supported  under  GRASS  3.0,  but  there  are  plans  to  su^^rt 
it  in  later  versions.  The  routines  in  this  library  are  written  with  this  upgrade  in  mind. 
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vector  access: 

dlgjiit  (fd)  imHalisB  level  one  vector  access 

FlLE*fd; 

Initialize  for  Level  One  access.  The  file  desciiptor  fd  is  lewoimd,  the  header 
information  is  extracted  and  stored  away,  and  M  is  positioned  to  read  the  first  arc 
in  the  file. 

Retnms  0  if  ok,  or  a  n^ative  value  if  error. 

Note.  This  routine  MUST  be  called  before  using  any  other  Level  One  routines, 
digjiewilld  (fd)  rewind  vector  file 

FLLEHd; 

The  file  descriptor  fid  is  rewound,  tfie  header  information  is  extracted  and  stored 
away,  and  fd  is  positioned  to  read  the  first  arc  in  the  file. 

Note.  This  routine  is  the  same  as  digj,nit{p.  125). 

Returns  0  if  ok,  or  a  negative  value  on  error. 

dig_prinDLheader  ( )  display  vector  header  infomvtion 

After  calling  (Sgjrdtip.  125),  selected  information  from  the  vector  ^le  header  can 
be  printed  to  stdout  using  this  routine. 

Return  value  is  undefined. 

Warning.  It  is  permissible  to  have  more  tiian  one  vector  file  open  for  Level  One 
access.  However,  this  routine  prints  the  header  information  extracted  by  the 
previous  call  to  either  225)  or  dig_rewind{p.  125). 

dig^fini  (fd)  end  level  one  vector  access 

FILE*fd; 


Terminate  Level  One  access.  To  be  called  when  finished  accessing  the  vector  file 
with  Leiel.  One  routines. 

Return  value  is  undefined. 

Note.  This  routine  does  ix)t  close  the  file  descriptor  fil  Use  fchse  ( )  to  close 
the  file  descriptor. 
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13.2.2.  Beadb^Aits 

The  next  routines  read  arcs  sequentially  fiom  the  vector  file. 


digjicadjiexLiiiie  (fd,  np,  x,  y)  get  next  arc 

FILE*fd; 
int  *rp; 

double  **x,  **y; 

The  points  constituting  the  next  arc  in  tiie  vector  file  open  on  fd  are  read  into 
hidden  arrays.  Pointers  to  these  anays  are  placed  in  x  ard  y,  and  np  is  set  to  the 
number  of  points  in  the  arc. 


Returns  the  arc  type:  LINE  or  AREA  (as  defined  in  "dig_defines.h"),  or  -2  if  no 
more  arcs,  or  -1  on  error. 

Note.  The  DOT  type  is  skipped  by  this  routine. 

Note.  The  programmer  must  pass  x  and  y  as  addresses  of  pointers.  For  example: 

FILE  *fd; 
int  np; 

double  *x,  *y; 

dig_read_next_line  (fd,  &np,  &x,  «&y); 


dig_rearLnextJine_^lJe  (fd,  rp,  x,  y,  type)  get  next  arc  by  type 

FILE*fd; 
int  np; 

double  **x,  **y; 
int  type; 

Same  as  c}ig_read_nextjine{p.  126)  except  that  it  limits  the  search  to  the  ^)ecified 
type,  which  can  be  any  combination  of  LINE,  AREA,  or  DOT. 

For  example,  to  read  the  next  LINE  or  AREA: 

FILE  *fd; 
int  np; 

double  *x,  *y; 

(lig_reacLnexl^line_type  (fd,  &np,  &jc,  &y,  LINE  ]  AREA); 


Returns  the  arc  type;  LINE,  AREA  or  DOT  (as  defined  in  "dig_defines.h"),  or  -2 
if  no  more  arcs,  or  -1  on  error. 
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(fiS^JnttJbax  (N,  S,  W)  Unit  arc  search  in  box 

double  N,  a  E,  W; 

Define  a  window  widnn  which  to  search  for  arcs  usiiTg 
cligj^adJineJiUx)xip.l27).  This  allows  the  programmer  to  limit  tiie  arcs 
retrieved  to  those  within  the  window  q)ecified  by  N  (noith),  S  (soudi),  E  (east), 
andW  (west). 

The  window  must  have  N  >  a  and  E  >  W. 

Returns  0  if  window  is  valid,  or  n^ative  on  arror. 

Note.  This  routine  does  NOT  change  the  position  of  the  file  pointer.  In 
particular,  it  does  not  rewind  the  file. 

digjniaClJmeJnJxK  (fd,  np,  x,  y)  readarc  in  box 

FILE*fd; 
int  *np; 
doible  **x, 

Same  as  dig_read_nextjine(p.  126)  except  that  it  only  looks  inside  die  bounding 
box  set  by  digJ,TutJbox(p.  127). 

Note  This  routine  only  ignores  arcs  which  are  completely  outade  the  bounding 
box.  If  any  part  of  die  arc  falls  within  the  bounding  box,  the  entire  arc  is  read, 
including  the  parts  outside  the  box.  No  clipping  is  performed. 


13,3.  Levd  Twd  Read  Access 

This  level  provides  full  access  to  all  the  information  contained  in  the  vector  file  and  its 
siqiport  files.  Arc,  area,  and  node  information  is  available,  including  the  internal 
indexes  for  each  entity,  as  well  as  category  attributes. 

The  indexes  are  unique,  and  can  be  used  to  distinguish  one  area  from  anodier,  or  one 
arc  from  another.  Note,  however,  that  different  areas  may  have  the  same  cat^ory 
attribute  (as  may  different  arcs). 


13.3.1.  InitializatkmTerninaticxi 

The  foUowmg  routines  perform  initialization  and  termination  actions  for  Level  Tho 
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vector  access; 

^gJPJbnit  (name,  mapset,  map)  initialize  level  two  vector  access 

char  *name; 

char  *mapset; 

struct  M^Jmfo  *map; 

Tnitiali7.p  Level  Tliv  read  access  to  vector  file  name  in  mapset.  This  routine 
opens  any  files  it  will  need. 

Return  value  is  undefined.  This  routine  will  exit  on  any  error  and  print  a 
description  of  the  error. 

Note.  This  routire  MUST  be  called  before  calling  any  other  Lei^l  Two  routines. 


digJLfini  (map) 

struct  Mapjmfo  *map; 

Terminate  Level  Two  access  for  mapt 
digJ*Jmt{p.  128). 


end  level  two  vector  access 

This  routine  closes  arty  files  opened  by 


d^J>_tmp_cl09e  (map)  temporary  close  vector  map 

struct  Mapjnfo  *map; 

Temporarily  close  access  to  mapc  This  is  useful  to  free  one  open  file  while  not 
needed. 


Return  is  undefined. 


rtig  P  tmp  cyen  ( m£p)  leopen  closed  vector  map 

struct  Mapjnfo  *map; 

Reopen  a  map  that  has  been  closed  with  dig_PjTrp_close{p.  128). 

Return  value  is  undefined.  If  map ->  digit  ==  NULL,  then  the  call  faded. 


13.3.2.  Area  Retrieval 

The  following  routines  retrieve  area  information. 
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digJ*_JlillL.area8  (map)  get  mmber  of  areas 

struct  Mapjnfo  *map; 

Return  total  number  of  areas  in  the  vector  hkqx 

Nota  The  area  indexes  are  numbered  from  1  to  n,  where  n  is  the  number  of 
areas  in  tiie  vector  file,  as  returned  by  this  routine. 

digJ*_getLai«L-xy  (map,  n,  np,  x,  y)  get  area  polygon 

struct  M^Jnfo  *map; 

intn; 

int  *Tto; 

double  **x,  **y; 

(jiven  area  index  n,  all  toe  points  for  toe  area  are  read  into  hidden  arrays. 
Fbinters  to  these  arrays  are  placed  in  x  and  y.  Points  are  in  clockwise  order. 
The  pointers  x  and  y  are  valid  until  toe  next  call  to  this  routine. 

Returns  0  if  found,  or  negative  on  error. 

Note.  The  programmer  must  pass  x  and  y  as  addresses  of  pointers: 

struct  Mapjnfo  map; 
intn,  lip; 
double  *x,  *y; 

dig_P_get_ansajcy  (&mEp,  n,  &np,  &x,  &y); 

digJP_0Et_area  (map,  n,  pa)  get  area  polygon 

struct  Map_info  *map; 
int  n; 

P_j\REA  **pa; 

Given  area  index  n,  the  PJSEEA  information  for  the  area  is  read  into  a  hidden 
structure.  A  pointer  to  this  structure  is  placed  in  pa  The  pointer  pa  is  valid 
until  toe  next  call  to  this  routine. 

Returns  0  if  found,  or  negative  on  error. 
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digJP_area_att  (map,  n)  g^t  ana  category  attribute 

struL't  MtqjJiifo  *map; 
intn; 

Given  area  index  n,  return  its  category  number. 

Returns  0  if  not  an  area  or  if  unlabeled 

digj*_get_area^bbax  (map,  n,  N,  S,  E,  W)  get  area  bounding  box 

Struct  Mapjnfo  *map; 
intn; 

double  *N,  *S,  *E,  *W; 

C^ven  area  index  n,  set  N  (north),  S  (south),  E  (east),  and  W  (west)  to  the  values 
of  the  bounding  box  for  the  area 

Returns  0  if  ok,  or  -1  on  error. 


13.3.3.  Arc  Retrieval 

The  following  routines  retrieve  arc  information. 

dligJ*J*IirLJines  (rnap)  get  nunber  of  arcs 

struct  Map_info  *map; 

Returns  total  number  of  arcs  in  the  vector  nc^x 

Note.  The  arc  irxlexes  are  numbered  from  1  to  n,  where  n  is  the  number  of  arcs 
in  the  vector  file,  as  returned  by  this  routine. 

dig_P_read_Ii^ie  (map,  n,  p)  leadarc 

struct  Map_info  *m£p; 
int  n; 

struct  line_pnts  p; 

Given  arc  index  n,  the  points  for  the  arc  are  read  into  a  hidden  Une^nts 
structure.  A  pointer  to  this  structure  is  placed  in  pi  The  pointer  p  is  valid  until 
the  next  call  to  this  routine  or  to  dig_P _read_nextj,we(p.  131 ). 

Returns  the  same  values  as  dig^pnd_mxtjine{p.  126). 
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digJ^JPead.JlBKUilie  (m^,  p)  read  next  arc 

struct  Mapjnfo  *mBp; 
struct  line_pnts  **p; 

The  points  for  the  next  arc  in  the  vector  map  are  read  into  a  hidden  Unejmts 
structure.  A  pointer  to  this  structure  is  placed  in  pi  The  pointer  p  is  v^d  until 
die  next  call  to  fliis  routine  or  to  dig_PjreadJine(p.  130). 

Returns  die  same  values  as  (£g_read_nextjijie(p.  126). 

dig^Pjrewind  (map)  rewind  next-aiv  pointer 

struct  Map_info  *m£?); 

Resets  the  next-arc  pointer  to  beginning  of  list  For  use  with 
digj*_read_pext_lirte{p.l31). 

Return  is  undefined. 

digJP_Inie_att  (map,  n)  get  arc  category  attribute 

struct  Mapjnfo  *m£p; 
intn; 

Given  arc  index  n,  return  its  category  number. 

Returns  0  if  not  labeled  or  on  error. 

digJ*_getJiiie_bbax  (map,  n,  N,  S,  E,  W)  get  arc  bounding  box 

struct  Mapjnfo  *map; 
int  n; 

double  *N,  *S,  *E,  *W; 

Given  arc  itxlex  n,  set  N  (north),  S  (south),  E  (east),  and  W  (west)  to  the  values 
of  the  bounding  box  for  the  arc. 

Ftetums  0  if  ok,  or  negative  on  error. 


13.3.4.  Ar^  Analysis  Tools 

The  following  routines  provide  some  area-related  analyses. 
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dig_poillLto_area  (map,  x,  y)  find  area  with  point 

struct  Mapjnfo  *inap; 
double  X,  y; 

Returns  the  index  of  the  area  containing  die  point  x,y,  or  0  if  none  found- 
double 

dig_pointJn_area  (map,  x,  y,  paO  point  in  area 

struct  Mapjnfo  *map; 
double  X,  y; 

P^AREA.  *pa; 

Given  a  filled  P^AREA  structure  pa,  detemnines  if  x,y  is  within  the  area  The 
structure  pa  can  be  filled  with  digj*^et_area(p.  129). 

Returns  0.0  if  x,y  is  not  in  the  area,  the  poative  Tninimnm  distance  to  the  nearest 
area  edge  if  x,y  is  inside  the  area,  or  -1.0  on  error. 


13.3.5.  Arc  Analysis  Tools 

The  following  routines  provide  some  arc-related  analyses. 

dig_point.tojine  (map,  x,  y,  type)  find  atv  with  poiiu 

struct  Mapjnfo  *m^; 
doiiile  X,  Y, 
char  type; 

Returns  the  index  of  the  arc  which  is  nearest  to  tiie  point  xty.  The  point  x,y  must 
be  within  the  arc’ s  bounding  box.  Set  type  to  a  combination  of  LINE,  AREA  or 
DOT  (e.g.,  LINE  [  AREA),  or  (char)-l  if  you  want  to  search  all  arc  types. 

dig_check_dist  (map,  n,  x,  y,  d)  distance  to  ojv 

struct  Mapjnfo  ^map; 
int  n; 

double  x,  y; 
double  *d; 

Conrputes  d,  the  square  of  the  minimum  distance  from  point  x,y  to  arc  n 

Returns  the  number  of  the  segment  that  was  closest,  or  -1  on  error.  The  segment 
number,  in  combination  with  dig_P_readJim{p.  130)  can  be  used  to  determine  the 
end-points  of  the  closest  line-segment  in  the  arc: 
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struct  Map.info  ixiep; 
ck>vble  X  j,d; 
double 
intn; 

struct  line_pnts  *p; 

if  ((s  =  dig_check_dist(&a«p,  n,  x,  y,  &d))  >  0) 

{ 

dig_P_reacLliiie  (&niap,  n,  &p); 
xl  =  p->x[s-l]; 
yl  =  p->yts-l]; 
x2  =  p->x[8]; 
y2  =  p->y[s]; 

} 

13.4.  Writii^  Binary  Dig  files 

The  following  routines  are  provided  for  import  and  eaqwrt  capabilities. 

Note.  The  file  descriptors  required  by  tfiese  routines  should  be  either  open  for  writing, 
or  for  reading,  but  not  for  both  writiig  and  reading. 

long 

digAVriteJine  (fd,  type,  x,  y,  np)  write  arc 

FILE*fd; 
char  type; 
double  *x,  *y; 
intnp; 

Writes  the  arc,  defined  by  the  np  points  in  the  x  sand  y  amays,  to.  the  end  of  the 
binaiy  dig  vector  file  open  on  file  descriptor  fd.  The  arc  type  must  be  one  of 
LINE,  AREIA,  or  DOT. 

Returns  the  of^t  in  the  file  where  the  arc  was  written.  This  offset  can  be  used 
with  digjieadjineip.  133). 

digJReadJine  (fd,  offset,  x,  y,  np)  read  arc 

FD^  ’•Td; 
long  offset; 
double  **x,  *  'ty; 
int  *np; 

Seeks  to  the  specified  olCset  on  file  descriptor  fd  and  reads  the  arc  which  begins 
there  into  hidden  arrays.  Pointers  to  these  anays  are  then  placed  into  x  and  y  and 
np  is  set  to  the  number  of  points  in  the  arc. 

Return  is  the  same  as  dig_read_nextjim{p.  126)  from  Level  One. 
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Nbte.  The  programmer  must  pass  x  and  y  as  addresses  of  pointeis: 

FlLE*fd; 
long  offset; 
intnp; 

double  *x,  *y; 

dig_Eead_line  (fd,  offset,  &x,  &y,  &np); 


dig^reacLheacLbinaKy  (fd,  header)  read  vector  header 

FTLE^fd; 

struct  digjiead  *header, 

Reads  the  header  from  the  binary  dig  vector  file  open  on  file  descriptor  fd  It 
can  be  used  to  position  fd  ready  to  read  the  first  arc  in  the  file. 

Currently  only  returns  0. 

Note.  If  using  Level  One  routines,  it  is  unnecessaiy  to  call  this  routine. 


dig_writeJiea(Lfainaiy  (fd,  header)  write  vector  header 

FILE*fd; 

struct  dig_head  ^header, 

Writes  the  header  information  to  the  binary  dig  vector  file  open  on  file  descriptor 
fd  This  routine  must  be  the  first  to  write  to  a  new  vector  file.  After  the  heEder 
has  been  written,  arcs  can  be  sequentially  written  to  the  file.  It  can  also  be  used 
to  rewrite  the  header  information  after  the  entire  file  has  been  written,  if 
necessary. 

Cumentiy  only  returns  0. 


13.5.  Misoeflaiieous  Tools 

double 

dig^distanoe2_point_tojilie  (x,  y,  xl,  yl,  x2,  y2)  distance  to  line-segment 

double  X,  y; 
double  xl,  yl,  x2,  y2; 

Confutes  the  square  of  the  minimum  distance  from  point  x,y  to  the  line-segment 
xlo^l,x2,y2. 

Returns  the  distance  squared. 
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double 

dig^_dslanceSLpcnit.toJ^  (x,y^l,yl^,y2)  distance  to  Une-segmnt 

double  *x,  *y; 
double  xl,  yl,  x2,  y2; 

Returns  die  square  of  the  mmimum  distance  finm  point  to  the  line-s^to^ 
xlo^l,x2o^ 

Changes  to  the  point  on  the  segment  xl^l,x2^  l^dlich  is  closest  to 

dig_pruiie  (p,  threshold)  prune  a  dense  arc 

struct  line_pnts  *p; 
double  thr^hold; 

Given  a  filled  lim_pnts  structure  p,  prune  it  within  the  specified  threshold  This 
function  is  used  to  reduce  the  number  of  points  needed  to  define  an  arc  within  a 
given  accuracy. 

Returns  the  new  number  of  points. 

<fig_b(ll]nd.bax  (p,  N,  S,  El,  W)  arc  bounding  box 

struct  line_pnts  *p; 
double  *N,  *S,  *E;  *W; 

Given  a  filled  line_pnts  structure  p  contaiisng  a  list  of  X,Y  coordinates,  compute 
the  boundirtg  box  of  this  list 

Returns  noivzero  on  error. 


13.6.  Ixiodiiig  the  Dig  Library 

The  library  is  loaded  by  specifying  $(DIGLIB)®  in  the  Gmakefile.  The  foUowirig 
example  is  a  complete  Gmakefile  which  compiles  code  that  uses  this  library; 


^  This  variable  was  NOT  defined  in  releases  3.0  and  3.0A.  Edit  the  file 
$GISBASEl/sic/CMDAmke .nid  and  add  the  line:  DIGLIB=$(SRO/mapdev/lib/digUKa  at  the 
bottom  of  the  file. 
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_ -jiBkefile  for  $(DI(HJB) _ 

OBJ  =  iraiiLO  sii)l.o  sub2.o 
EXTRA^CFIAGS  =  -I$(SRC)Anapdevylib 

pgm:  $(OBJ)  $(DIGLIB) 

$(CC^  $(LDFLAGS)  -o  $@  KOBJ)  $(DI(3JB) 

$(DIGLJB):  *  in  case  the  libiay  changes _ 


Note.  EXTRA^CFLAGS  tElls  the  C  compiler  where  additional  ^include  files  are 
located.  This  is  necessary  sirx:e  the  required  #include  files  do  not  live  in  the  normal 
GRASS  ^include  directory. 

See  §iJ  Corrpiling  GRASS  Pmgrams  Using  Grnahe  \p.55]  for  a  complete  discussion  of 
Gmakefiles. 
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Chapter  14 

Imagery  LOnrary 


141.  Introduction 

The  Imagery  Lihrary  was  created  for  version  3.0  of  GRASS  to  si^port  integrated 
image  processing  directly  in  GRASS.  It  contains  routines  that  provide  access  to  the 
group  database  structure  which  was  also  introduced  in  GRASS  3.0  for  the  same 
purpose.^ 

It  is  assumed  that  the  reader  has  read  §4  Database  Structure  \p.l5\  for  a  gereral 
description  of  GRASS  databases,  §S  hvage  Data:  Groups  \p.4l]  for  a  description  of 
imagery  groups,  and  §5  Grid  Cell  Maps  lp.23]  for  details  about  map  layers  in  GRASS. 

The  routines  in  the  Imagery  library  are  presented  in  functional  groupings,  rather  than 
in  alphabetical  order.  The  order  of  presentation  will,  it  is  hoped,  provide  a  better 
understanding  of  how  the  library  is  to  be  used,  as  well  as  show  the  inter-relationships 
among  the  various  routines.  Note  that  a  good  way  to  understand  how  to  use  these 
routines  is  to  look  at  tiie  source  code  for  GRASS  programs  which  use  them.^ 

Most  routines  in  this  library  require  that  the  header  file  "imageiy.h"  be  irKluded  in  ary 
code  using  these  routines.^  Therefore,  programmers  should  always  include  this  file 
when  writing  code  using  routines  from  this  library; 

#  include  "imagery.h" 


This  header  file  includes  the  "gis.h"  header  file  as  well. 

Note.  All  routines  and  global  variables  in  this  library,  documented  or  undocumented, 
start  with  the  prefix  I_.  To  avoid  name  conflicts,  programmers  should  not  create 

1  Since  this  is  a  new  library,  it  is  expected  to  grow.  Hopefully,  image  analysis  functions  will 
be  added  to  complement  the  database  functions  already  in  the  library. 

^  See  §5.4  Irrageiy  Pivgrturs  \p.  45]  for  a  list  of  some  imagery  programs. 

Tire  GRASS  conrpilation  process,  described  in  §72  CorrpUitig  GRASS  Pivgmrrs  Using 
Grmke  [p.  5.5|,  automatically  tells  the  C  corxpiler  how  to  find  this  and  other  GRASS  healer  files. 
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vaiiables  or  routines  in  their  own  progrEons  which  lee  this  prefix. 

An  alphabetic  index  is  provided  in  §24.5  Appendix  E.  Index  to  Imagery  Library  \p.245\. 


142.  Group  RrooesEmg 

The  groiq)  is  the  key  database  structure  which  permits  integration  of  image  processing 
in  GRASS. 


142.1.  I¥onipting  for  a  Graiq) 

The  following  routines  interactively  prompt  the  user  for  a  group  name  in  the  current 
m^jset'*  In  each,  the  pronpt  string  will  be  printed  as  the  first  line  of  the  full  prompt 
which  asks  the  user  to  enter  a  groi^  name.  If  prompt  is  the  empty  string  then  an 
appropriate  prompt  will  be  substituted.  The  name  that  the  user  enters  is  copied  into 
the  groiq)  buffer.®  These  routines  have  a  built-in  ’  list  capability  which  allows  the  user 
to  get  a  list  of  existing  groups. 

The  user  is  required  to  enter  a  valid  groi?)  name,  or  else  hit  the  RETURN  key  to 
cancel  tte  request  If  the  user  enters  an  invalid  r^ponse,  a  message  is  printed,  and  the 
user  is  prompted  agaiii  If  the  user  cancels  tiie  request  0  is  returned;  otherwise,  1  is 
returned 

I_aEk_gravqp_ald  ( prompt  group)  prompt  for  an  existing  givup 

char  *prorrpt 
char  *groi9); 

Asks  the  user  to  enter  the  name  of  an  existirig  in  the  current  m^)set 

( prompt  groiqj)  pmrrpt  for  mw  group 

char  ^prompt 
char  ^grotp; 

Asks  the  user  to  enter  a  name  for  a  graiq)  which  does  rx)t  exist  in  the  current 
mapset 


This  libtBiy  only  works  with  groups  in  the  current  mapeet  Other  mapsets,  even  those  in 
the  user^  s  mapset  search  path,  are  ignored. 

®  The  size  of  graif>  should  be  large  eix)ugh  to  hold  any  GRASS  file  name.  Most  systems 
allow  file  names  to  be  quite  long.  It  is  recommeixied  that  name  be  declared  chw  gioupl 50] . 
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I  asfc  group  any  (pronopt,  group)  pronpt  for  any  valid  group  none 

char  *protnpt; 
char  *group; 

Asks  the  visa*  to  enter  a  valid  0xiiq>  name,  llie  may  or  may  not  exist  in 
the  current  mapset 

Note  The  user  is  not  warned  if  the  graixp  exists,  llie  progtammer  should  use 
IJind^groupip.  139)  to  determine  if  the  gPOiq>  exists. 

Here  is  an  example  of  how  to  use  these  routines.  Note  that  the  programmer  must 
handle  tfie  0  return  property: 

char  grou?)[50]; 

if  (  !  Lask..groijp_any  ("EiitBr  groip  tn  be  proceesed",  groiq))) 
exittO); 


14.2:2.  Finding  Gimps  in  rtie  Database 

Sometimes  it  is  necessary  to  determine  if  a  given  group  already  exists.  The  following 
routine  provides  this  service: 

IjSncLgrotp  (group)  ches  gjoip  exist? 

char  *groip; 

Returns  1  if  the  specified  group  exists  in  tiie  current  mapset;  0  otherwise. 


14.2.a  REFFfie 

These  roirtines  provide  access  to  the  iitformation  contained  in  tiie  REF  file  for  groups 
and  subgroups,  as  well  as  routines  to  update  this  information  'Ibey  uise  the  Eef 
structure,  which  is  defined  in  the  "imagery .h"  header  file;  see  §24.4  Imagery  library 
Data  Structures  Ip.  144]. 

The  contents  of  the  REF  file  are  read  or  updated  by  the  following  routines: 
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I_get_gPOI5>_jnEf  (gn)i;p,  ref)  read  groip  REF  fie 

char  *gn)i?); 
struct  Ref  *ref; 

Reads  the  contents  of  the  REP  file  for  the  specified  graiq>  into  the  ref  structure. 
Returns  1  if  successful;  0  otherwise  (but  no  error  messages  are  printed). 

Lput_groBqpL-ref  (groip,  ref)  write  group  BEF  file 

char  *groi5); 
struct  Ref  *ref; 

Writes  the  contents  of  the  ref  structure  to  the  REF  file  for  the  specified  groiq). 
Returns  1  if  successful;  0  otherwise  (and  prints  a  diagrxrstic  error). 

Note.  This  routine  wUl  create  the  groiqi,  if  it  doesn’ t  already  exist 

I_getjsubgroup_rrf  {group,  subgroup,  ref)  read  subgroup  BEF  file 

char  *groi:p; 
char  *subgroup; 
struct  Ref  *ref; 

Reads  die  contents  of  the  REF  file  for  the  specified  subgrotq)  of  the  specified 
groiq)  into  the  ref  structure. 

Returns  1  if  successful;  0  otherwise  (but  no  error  messages  are  printed). 

I_p«t_Sld)gr045>_JTf  (group,  subgroup,  ref)  write  subgroup  BEF  file 

char  *group; 
char  *subgroup; 
struct  Ref  *ref^; 

Writes  the  contents  of  the  ref  structure  into  the  REF  file  for  the  specified 
sul^roup  of  the  specified  groiq}. 

Returns  1  if  successful;  0  otherwise  (and  prints  a  diagnostic  error). 

Note.  This  routine  will  create  the  suf^iroup,  if  it  doesn’ t  already  exist 


These  next  routines  manipulate  the  Btf  structure: 
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I  init  grmy  ref  (ref)  imtialue  Ref  stnctiat 

Struct  Ref  *ref; 

This  routine  initializes  the  rrf  structure  for  otijer  library  calls  which  require  aife/" 
structure.  This  routine  must  be  called  before  any  use  of  the  structure  can  be 
made. 

Note.  The  routines  I_get_groiip_ref{p.  140)  and  I_get_$ubgroi4)_refip.  140)  call  this 
routine  automatically. 

I_addjBle_to_group_jief  (name,  mapset,  ref)  add  file  name  to  Ref  sbrcture 

char  *name; 
char  *mapset; 
struct  Ref  *ref; 

This  routine  adds  the  file  name  and  ma|Het  to  the  list  contained  in  the  ref 
structure,  if  it  isn’t  already  in  tiie  list  The  ref  structure  must  have  been  properly 
initialized. 

This  routine  is  used  by  programs,  such  as  i.maxUk,  to  add  to  the  group  new  cell 
files  created  from  files  already  in  the  groiQ). 

Returns  the  index  into  the  file  arrsy  witim  the  nef  structure  for  the  file  after 
insertion;  see  ^14.4  Imagery  library  Data  Structures  [p.l44]. 

I_tiOTsfer_groiq)_j€f_file  (src,  n,  dst)  copy  Ref  lists 

struct  Ref  *src; 
int  n; 

struct  Ref  *dst; 

This  routine  is  used  to  copy  file  names  from  one  Ref  structure  to  another.  The 
name  and  mapset  for  file  n  from  the  arc  structure  are  copied  into  the  dst  structure 
(which  must  be  properly  initialized). 

For  example,  the  following  code  copies  one  Ref  structure  to  another: 

struct  Ref  src, dst; 
int  n; 

f*  some  code  to  get  infoimalion  into  arc  */ 


LiniLgroup.nef  (&dst); 
for  (n  =  0;  n  <  src.nfiles;  iH+) 

Ltranrfer_gn)up_ref_file  (&ac,  n,  &dst); 

This  routine  is  used  by  i.points  to  cnsate  the  REF  file  for  a  subgroup. 
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LfiieeLgrai5>_ref  (ref)  five  Ref  structure 

struct  Ref  *ref; 

This  routine  frees  memory  aUocated  to  the  ref  structure. 


142.4  TARGET  File 

The  following  two  routines  read  and  write  the  TARGET  file. 

I  get  target  (group,  location,  mapset)  read  target  irforrmtion 

char  *grotp; 
char  ^location; 
char  *m^jset; 

Reads  the  target  locatiai  and  mapset  irom  the  TARGET  file  for  the  specified 

group 

Returns  1  if  successful;  0  otherwise  (and  prints  a  diagnostic  error). 

This  routine  is  used  by  i.points  and  i.rectify  and  probably  shouldri  t  be  used  by 
other  programs. 

Note  This  routine  does  not  validate  the  target  iitformatioa 

l_put_taiget  (group,  location,  mapset)  write  target  infomvtion 

char  *groip; 
char  ^location; 
char  *mapset; 

Writes  the  target  locatian  and  mapset  to  the  TARGET  file  for  the  specified 

group 

Returns  1  if  successful;  0  otherwise  (but  no  error  messages  are  printed). 

Th's  routine  is  used  by  i.target  and  probably  shouldn’t  be  used  by  other 
programs. 

Note.  This  routine  does  not  validate  the  target  information 
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142.6.  POIM^Fife 

Tte  following  routines  read  and  write  the  POINTS  file,  which  contains  the  image 
lustration  control  points.  Ihis  file  is  created  and  li^Klated  by  the  program  upoints,  and 
read  by  LrecUfy. 

Ttese  routines  use  the  Control_Points  structure,  which  is  defined  in  the  "imageiy.h" 
header  file;  see  %14.4  Imagery  Library  Data,  Structures  [p.  144]. 

Note.  The  interface  to  the  ControlJ^oints  structure  provided  by  the  routines  below  is 
incomplete.  A  routine  to  initialize  the  structure  is  needed. 

I_get_COntroLpauits  (grot?>,  cp)  read  group  control  points 

char  *groito; 

struct  ControLJPoints  *cp; 

Reads  the  control  points  from  the  POINTS  file  for  the  groiq>  into  the  cp 
structure. 


Returns  1  if  successful;  0  otherwise  (and  prints  a  diagnostic  error). 

Note.  An  error  message  is  printed  if  tiie  POINTS  file  is  invalid,  or  doesri  t  exist 

I jnew_OGntit)l_pGint  (cp,  el,  nl,  e2,  n2,  status)  add  mw  control  point 

struct  ControUPoints  *cp; 
doiiole  el,  nl; 
double  e2,  n2; 
uit  status. 

Once  the  control  points  have  been  read  into  the  structure,  this  routine  adds 
new  points  to  it  The  new  control  point  is  given  by  el  (column)  and  nl  (row)  on 
the  image,  and  the  e2  (east)  and  n2  (north)  for  the  target  database.  The  value  of 
status  should  be  1  if  the  point  is  a  valid  point;  0  otherwise.® 


Uae  of  this  routine  irrplies  that  the  point  is  probably  good,  so  statiB  should  be  set  to  1. 
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L-PUtLOontroLpoinis  (groi;^,  cp)  urite  gmup  control  points 

char  *gn)i5); 

struct  ControLJoints  *cp; 

Writes  the  control  points  from  tiie  cp  stmcture  to  the  POINTS  file  for  the 
specified  gratqx 

Note.  Points  in  <p  with  a  n^ative  status  are  not  written  to  the  POINTS  file. 


143.  Loadii^  flte  Ims^eiy  IJbrar^ 

The  library  is  loaded  by  specifying  $(IMAGERYLIB)  in  the  Gmakefile.  The 
following  example  is  a  conplete  (jknakefile  which  compiles  code  that  uses  this  library: 

_ Gknakefile  for  $(IMAGKKYLIB) _ 

OBJ  =  main.0  sibl.o  sub2.o 

$(OBJ)  $(IMA.GERYLIB)  $(GISIJB) 

$(CC)  $(LDFIAGS)  -o  $@  $(OBJ)  SOMAGERYUB)  $(GISLIB) 

$(IMAGE31YLJB):  *  in  case  the  libraiy  changes 

$(GISLIB): _ *  in  case  the  library  changes 


Note  This  libraiy  must  be  loaded  with  $(GISLIB)  since  it  uses  routines  finm  that 
library.  See  §i2  GIS  library  \p.  63]  for  details  on  that  library. 

See  §ii  Compiling  GRASS  Programs  Using  Gmake  [p.55]  for  a  complete  discussion  of 
Gmakefiles. 


144  lni£^ery  Libraiy  Data  S(r^ 

Some  of  the  data  structures  in  the  "imagery.h"  header  file  are  described  below. 


144.1.  struct  Ref 

The  Ref  structure  is  used  to  hold  the  information  from  the  REF  file  for  groups  and 
subgroups.  The  structure  is: 
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structBef 

{ 


int  nfiles; 
struct  Ri^_FQes 
{ 

char  name[30]; 

/" 

nunber  of  REF  files 

*/ 

/* 

REIFfile  name 

’"/ 

char  mapeet[30]; 

}  *file; 

struct  ReLColor 
{ 

unsigned  char  ’"table; 

/" 

REF  file  mapset 

*/ 

/* 

color  taUe  for  nin-n'jax  values 

*! 

unagned  char  ’"index; 

data  trandation  index 

*! 

unsigned  char  ’"buf; 

!*■ 

data  buffer  for  reading  color  file 

*! 

intfd; 

/* 

for  image  i/o 

’"/ 

CELL  nin,  max; 

/* 

nin^nax  CELL  values 

’"/ 

intn; 

}  red,  gm,  blu; 

/* 

index  into  Ref  Jlles 

’"/ 

} ; 

The  Eef  structure  has  nfiles  (tiie  number  of  cell  files),  file  (the  name  and  mapset  of 
each  file),  and  red,gmjblu  (color  information  for  the  group  or  stbgrovp^). 

There  is  no  function  interface  to  the  nfiles  and  file  elements  in  the  structure.  This 
means  that  the  programmer  must  reference  the  elements  of  the  structure  directly.®  The 
name  and  mapset  for  the  i  th  file  are  filelij.nane ,  and  file[i]  .mapset . 

For  example,  to  print  out  the  names  of  the  cell  files  in  tiie  structure: 

inti; 

struct  Ref  ref; 


/*  some  code  to  get  the  REF  file  for  a  group  into  ref  */ 


for  (i  =  0;  i  <  ref  .nfiles;  i++) 

printf  ("%s  in  %s\n",  refiile[i].name,  ref.file[i].m^Met); 


144.2.  struct  CotriraLPauits 

The  ControlJPoints  structure  is  used  to  hold  the  control  points  from  the  group 
POINTS  file.  The  structure  is: 


^  The  ndgrriyblu  elements  are  expected  to  change  as  the  imagery  code  develops.  Do  not 
reference  them  Retend  they  don’ t  exist 
^  The  iifiks  and  fUe  elements  are  not  expected  to  change  in  the  future. 
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struct  ControLIbintB 
{ 


int  count; 

/• 

nunnber  of  control  poitds 

*/ 

double 

/* 

imftge  east  (colunn) 

*/ 

double  *nl; 

/* 

image  north  (row) 

*! 

double  *e2; 

/* 

taigeteast 

*! 

double  *n2; 

/* 

target  north 

*! 

int ’"statue; 

/* 

status  of  control  point 

*/ 

} ; 

The  number  of  control  points  is  count.  Control  point  i  is  el  [i],  ni[i],  e2[i],  n2[i], 
and  its  status  is  status  [i]. 
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Chapter  15 

Raster  Grapbks  Library 


15.1.  Inteoduction 

The  Raster  Graphics  Library  provides  the  programmer  with  access  to  the  GRASS 
graphics  devices.  All  video  grspincs  calls  are  made  1hroii|^  dns  library  (Erectly 
cr  indirecdy).  No  standard/portable  GRASS  video  gr^hics  program  drives  any  video 
display  directly.  This  library  provides  a  powerful,  but  limited  number  of  graphics 
cai^ilities  to  the  programmer.  The  tremendous  benefit  of  this  approach  is  seen  in  the 
ease  with  which  GRASS  graphics  applications  programs  port  to  new  machines  or 
devices.  Because  no  device-dependent  code  exists  in  ^plication  programs,  virtually 
all  GRASS  graphics  programs  port  without  modificatioa  Each  graphics  device  must 
be  provided  a  driver  (or  transLator  program).  At  rurt-time,  GRASS  graphics  programs 
rendezvous  with  a  user-selected  driver  program.  Two  significant  prices  are  paid  in  this 
approach  to  graphics:  1)  graphics  displays  run  agnificantly  slower,  and  2)  the 
programmer  does  not  have  access  to  fairy  (and  sometimes  more  efficient)  resident 
libraiy  routines  that  have  been  specially  created  for  the  device. 

This  libraiy  uses  a  cotple  of  sinple  concepts.  First,  there  is  the  idea  of  a  current 
screen  location  There  is  nothiirg  which  appears  on  the  graphics  monitor  to  indicate 
the  current  location,  but  many  grEphic  commands  begin  their  gr^hics  at  this  location 
It  can  of  course,  be  set  explicitly.  Second,  there  is  always  a  current  color.  Many 
graphic  commands  will  do  tfrir  woik  in  the  currently  chosen  color. 

The  programmer  always  worics  in  the  screen  coordinate  ^stem  Unlike  many  graphics 
libraries  developed  to  support  CAD,  there  is  no  concept  of  a  worid  coordinate  system. 
The  programmer  must  address  grephics  requests  to  explicit  screen  locations.  This  is 
necessaiy,  especially  in  the  interest  of  fast  raster  graphics. 

The  upper  left  hand  comer  of  the  screen  is  the  origin  The  actual  pixel  rows  and 
columns  which  define  the  edge  of  the  video  surface  are  returned  with  calls  to 
ILscreenJe/Up.150),  R^reenjiteip.isO),  LLscreenJbotip.  150),  and 
ILjcreenJopip.  150). 

Note,  All  routines  and  global  variables  in  this  libraiy,  documented  or  undocumented. 


§15  Raster  Graphics  Library 


-  148- 


-  148- 


stEot  with  the  pefbc  IL.  To  avoid  name  conflicts,  programmers  should  not  create 
vaiiables  or  routines  in  their  own  programs  which  use  this  prefix. 

An  alphabetic  index  is  provided  in  §24.5  Appendix  G.  Index  to  Easter  Graphics 
Library  Ip. 249]. 


15^.  CoiwiftthTg  to  the  Driver 

Before  any  other  graphics  calls  can  be  made,  a  successful  connection  to  a  running  and 
selected  graphics  driver  must  be  made. 

R_<^JaudrivEr  (  )  initialize  gmphics 

Initializes  connection  to  current  graphics  driver.  Refer  to  GRASS  Usei^  s  Manual 
entries  on  toe  monitor  command.  If  connection  cannot  be  made,  the  application 
program  sends  a  message  to  toe  user  stating  that  a  driver  has  not  been  selected  or 
could  not  be  opened.  Note  that  only  one  application  program  can  be  connected  to 
a  graphics  driver  at  once. 

After  all  graphics  have  been  completed,  toe  driver  should  be  closed. 

R_d08e_driver  (  )  teminate  graphics 

This  routine  breaks  the  connection  with  the  graphics  driver  opened  by 
R^open_driver( ). 


15,3.  Colors 

GRASS  is  highly  deperxlent  on  color  for  distinguishing  between  different  categories. 
No  graphic  patterning  is  sipported  in  any  automatic  way.  There  are  two  color  modes. 
Fixed  color  refers  to  set  and  immutable  color  look-up  tables  on  toe  hardware  device. 
In  some  cases  this  is  necessary  because  toe  graphics  device  does  not  contain 
programmer  definable  color  look-up  tables  (LUT).  Floating  colors  use  toe  LlTTs  of  toe 
graphics  device  often  in  an  interactive  mode  with  the  user.  The  basic  impact  on  toe 
user  is  that  under  the  fixed  mode,  multiple  maps  can  be  displayed  on  toe  device  with 
apparently  no  color  interference  between  maps.  Under  float  mode,  the  user  may 
interactively  manipulate  the  hardware  color  tables  (using  programs  such  as  d.colors). 
Other  than  the  fact  that  in  float  mode  no  more  colors  may  be  used  than  color  registers 
available  on  the  user' s  chosen  driver,  there  are  no  other  programming  repercussions. 
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RL.OQiar_tafalejfiBBd  ( )  select  fixed  color  table 

Select  a  fixed  color  table  to  be  used  for  subsequent  color  calls.  It  is  expected  that 
the  user  will  follow  this  call  with  a  call  to  erase  and  reinitialize  the  ‘ire 
graphics  screea 

Returns  0  if  successful,  non-zero  if  unsuccessful. 

B,_OQlor_tdble..float  ( )  select  floating  color  table 

Select  a  float  color  table  to  be  used  for  subsequent  color  calls.  It  is  expected  that 
the  user  will  follow  this  call  with  a  call  to  erase  and  reinitialize  the  entira 
grebes  screea 

Returns  0  if  successful,  non-zero  if  unsuccessful. 

Colors  are  set  using  integer  values  in  die  range  of  0-255  to  set  the  red,  green,  and 
blue  intensities  In  float  mode,  these  values  are  used  to  direedy  modify  the  hardware 
color  look-iQ)  tables  and  instantaneously  modify  the  appearance  of  colors  on  the 
monitor.  In  fixed  mode,  these  values  modify  secondany  look-iq)  tables  in  the  devices 
driver  program  so  diat  die  colors  involved  point  to  the  closest  asrailable  color  on  the 
device. 

RjieselLColor  (red,  green,  blu,  num)  define  single  color 

unagned  char  red,  green,  blue  ; 
intnum ; 

Set  color  number  num  to  the  intensities  represented  by  red,  green,  and  Uue 

Rjreset-oolors  (rain,max4ed,green,blue)  define  multiple  colors 

intmin,  max  ; 

unsigned  char  *red,  *green,  *blue  ; 

Set  color  nunbers  nin  dirough  max  to  the  intensities  represented  in  the  arra^ 
red,  green,  and  Uue: 

R_COlor  (color)  select  color 

int  color ; 

Selects  the  odw  to  be  used  in  subsequent  draw  commands. 
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RjgtandanLookr  (color)  select  standard  color 

int  color ; 

Selects  the  standard  color  to  be  used  in  subsequent  draw  commands.  Ihe  color 
value  is  best  retrieved  usiitg  Djranslatejtolorip.  167).  See  §26  Display  Graphics 
Library  (p.  159]. 

RJRGB_ador  ( red,green,blue)  select  color 

int  red,  green,  blue  ; 

When  in  float  mode  (see  ILcolorJable_f]oat(j>.  149)),  this  call  selects  the  color 
most  closely  matched  to  tihe  red,  green,  and  Wue  intensitLes  requested.  These 
values  must  be  in  the  range  of  0-255. 


15.4.  Basic  GrafMcs 

Several  calls  are  common  to  neariy  all  graphics  systems.  Routines  exist  to  detennine 
screen  dimensions,  as  well  as  routines  for  moving,  drawing,  and  erasing. 

R_SCreen^bot  (  )  bottom  of  screen 

Returns  die  pixel  row  number  of  the  bottom  of  the  screen. 


R_SCreerL.top  (  )  top  of  screen 

Returns  the  pixel  row  number  of  toe  top  of  the  screen 

R_SCreenJl€£t  (  )  screen  left  edge 

Returns  the  pixel  column  number  of  the  left  edge  of  the  screen 

R_screen_rite  (  )  screen  light  edge 

Returns  the  pixel  column  number  of  the  right  edge  of  the  screen 

RjllOve_ab8  tx,y)  move  cwrent  location 

int  X,  y; 

Move  the  current  location  to  the  absolute  screen  coordinate  x,y.  Nothing  is 
drawTi  on  the  screen 
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R,.jiiOViejrcl  (dx,dy)  rmve  current  location 

intdx, 

Shift  the  cmrent  screen  location  by  the  values  in  dx  and  dy. 

Newx  =  (Mdx  +  (bq 
Nlewy  =  CMdy  +  dy, 

Nothipg  is  diavm  on  the  screen 

RcOOniLabs  (x,y)  draw  line 

intx,  y, 

Draw  a  line  using  the  current  color,  selected  via  Rjtolorip.  149),  from  the  current 
location  to  the  location  specified  by  3c,y.  Tlie  cunent  location  is  iqxlated  to  x^y. 

R^contunel  ( dx,dy )  draw  line 

int  dx,  dy, 

Draw  a  line  using  the  current  color,  selected  via  Rjtolorip.  149),  from  the  current 
location  to  the  relative  location  specified  by  dx  and  dy*  current  location  is 
iqxlated: 

Niewx  =  Oldx  +  dx; 

Newy  =  Oldy  +  dy, 


R_bax_ab8  (xl,yl,x2,y2)  fill  a  box 

int  xl,yl; 
intx2,y2; 

A  box  is  drawn  in  the  current  color  using  the  coordinates  xl,yl  and  x2,y2  as 
opposite  comers  of  the  box.  The  current  location  is  iqxlated  to  x2,y2. 

R_bax_rd  (dx,dy)  fill  a  box 

int  dx,  dy, 

A  box  is  drawn  in  the  cunent  color  using  the  cunent  location  as  one  comer  and 
the  cunent  location  plus  dx  and  dy  the  opposite  comer  of  the  box.  The  current 
location  is  iqxiated: 

Newx  =  Oldx  +  dx; 

Newy  =  Oldy  +  dy, 
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R_.craB6  ( )  eroK  screen 

Erases  the  entiie  screen  to  black 

R_ftjsh  ( )  flu^  graphics 

Send  all  pending  graphics  commands  to  the  graphics  driver.  Ihis  is  doi£ 
automatically  when  graphics  input  requests  are  made. 


15^.  Bofy  CaDs 

In  many  cases  strings  of  points  are  used  to  describe  a  complex  line,  a  series  of  dots,  or 
a  solid  polygon.  Absolute  and  relative  calls  are  provided  for  each  of  these  operaidons. 

R_po^yd0la_afa8  (x,y,num)  draw  a  series  of  dots 

int  *x,  *y; 
intnum; 

Pixels  at  the  num  absolute  positions  in  the  z  and  y  anays  are  turned  to  the 
cxjTtent  color.  The  current  position  is  left  iqxiated  to  the  position  of  the  last  dot 

R_polydlriS-nel  (x,y,num)  draw  a  series  of  dots 

int  *x,  *y; 
intnum; 

Pixels  at  the  num  relative  portions  in  the  x  and  y  arrays  are  turned  to  the  current 
color.  Ihe  first  position  is  relative  to  the  starting  current  location;  the  succeeding 
positions  are  dial  relative  to  the  previous  position.  The  current  position  is  updated 
to  the  position  of  die  last  dot 

R_poly9^Ml_ai)8  (x,y,num)  draw  a  closed  polygon 

int  *x,  *y; 
intnum; 

The  num  absolute  positions  in  the  x  and  y  arrays  outline  a  closed  polygon  which 
is  filled  with  the  current  color.  The  cument  position  is  left  i^xlated  to  the  position 
of  the  last  point 
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(x,y,num)  dvw  a  closed  polygon 

int  *x,  *y; 

Int  num; 

The  num  relative  poations  in  the  x  and  y  anrays  oudine  a  closed  polygon  vinch 
is  filled  with  the  cunent  color.  The  first  position  is  relative  to  the  startii^g  current 
location;  the  succeeding  positions  are  than  relative  to  the  previous  poation.  The 
current  position  is  iplated  to  the  position  of  the  last  point 

Ii_pol34ine_abs  (x,y,nuni)  draw  an  open  polygon 

int  *x,  *Y, 
int  num; 

The  num  absolute  positions  in  die  x  and  y  anays  are  used  to  generate  a  raulti- 
segmeht  line  (often  curved).  This  line  is  drawn  with  the  current  color.  The 
current  position  is  left  updated  to  the  position  of  the  last  point 

Note.  It  is  not  assumed  diat  the  line  is  closed,  i.e.,  no  line  is  drawn  from  die  last 
point  to  the  first  point 

R_p(^iine_Jid  (x,y,num)  draw  an  open  polygon 

int*x,  *y; 
int  num; 

The  num  relative  positions  in  the  x  and  y  arrays  are  used  to  generate  a  multi¬ 
segment  line  (often  curved).  The  first  position  is  relative  to  the  starting  current 
location;  the  succeeding  positions  are  then  relative  to  the  previous  position  The 
current  position  is  iplated  to  the  position  of  the  last  point  This  line  is  drawn 
with  the  current  color. 

Note  No  line  is  drawn  between  the  last  point  and  the  first  point 


15.6.  Raster  Calls 

GRASS,  being  principally  a  raster-based  data  system,  requires  efficient  drawing  of 
raster  information  to  the  display  device.  These  cadis  provide  tiiat  capability. 
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Rjraster  (numjirows,withzero4?^^  draw  a  raster 

int  num,  nrows,  withzero  ; 
int*raster ; 

Starting  at  tfae  current  position,  the  num  colors  represented  in  the  raster  array  are 
drawn  for  nrams  consecutive  pixel  rows.  The  wttfazero  flag  is  used  to  indicate 
whether  0  values  ate  to  be  treated  as  a  color  (1)  or  should  be  ignored  (0).  If 
ignored,  those  screen  pixels  in  diese  locations  are  not  modified.  This  option  is 
useful  for  graphic  overisp^. 

RjsetLitGB.oolor  (red,green,blue)  initialize  graphics 

unsigned  char  red[256],  green[256],  blue[256]  ; 

The  three  256  member  arrays,  red,  green,  and  fahiev  establish  look-tp  tables 
which  translate  the  raw  image  values  supplied  in  RJiGB_raster{p.  154)  to  color 
intensity  values  which  are  then  displayed  on  the  video  screen  These  two 
commands  are  tailor-made  for  imagery  data  coming  off  sensors  which  give  values 
in  the  range  of  0-265. 

R_RGB_jasfier  (rTtim4irows4Bd,grEeii,blue,withzero)  draw  a  raster 

int  num,  nrows,  widizero  ; 
unsigned  char  *red,  *green,  *blue  ; 

This  is  useful  only  in  fixed  color  mode  (see  IL.colorJableJboed(p.  149)).  Starting 
at  the  current  position,  the  num  colors  represented  by  the  intensities  described  in 
the  red,  green,  and  Uue  arrays  are  drawn  for  nrows  consecutive  pixel  rows.  The 
raw  values  in  these  amays  are  in  the  range  of  0-255.  They  are  u^  to  map  into 
the  intensity  maps  which  were  previously  sent  with  R_setjiGB_coU)r{p.  154).  The 
wifhzcro  flag  is  used  to  indicate  whether  0  values  are  to  be  treated  as  a  color  (1) 
or  should  be  ignored  (0).  If  ignored,  those  screen  pixels  in  these  locations  are  not 
modified.  This  option  is  useful  for  graphic  overiays. 


15*7.  Test 

These  calls  provide  access  to  built-in  vector  fonts  which  may  be  sized  and  clipped  to 
the  programmers  specifications. 
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RjsetLWlndOfMr  ( tDp,bottom4eft,right)  set  text  clipping  window 

int  top,  bottom,  left,  right ; 

Subsequent  calls  to  RjeXtip.156)  will  have  tejrt  strii^  clipped  to  the  screen 
window  defined  by  to|)^  botton^  kft, 

R_font  (font)  choose  font 

char  *font ; 

Set  cunent  font  to  font  Available  fonts  are: 


FbntName 

Description 

cynic 

cyrillic 

ffsthgbt 

Gothic  Great  Britain  triplex 

ffothgrt 

Gothic  Gennan  triiiJex 

godutt 

Gothic  Italian  triplex 

greekc 

Greek  complex 

greekcs 

Greek  cotivlex  script 

Rteekp 

Greek  plain 

(QBeks 

Greek  amplex 

italicc 

Italian  complex 

italiccs 

Italian  complex  anall 

italict 

Italian  triplex 

romanc 

Roman  complex 

romancs 

Roman  complex  small 

lomand 

Roman  duplex 

lomanp 

Roman  plain 

tomans 

Roman  simplex 

romant 

Roman  triplex 

acriptc 

Script  complex 

scripts 

Script  simplex 

R_tedLjsize  (width,  height)  set  text  size 

int  width,  height ; 

Sets  text  pixel  width  and  height  to  widUi  and  hd^it 
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It_text  (text)  urite  text 

char  *t)ext ; 

Writes  tect  in  the  cument  color  and  font,  at  die  cunent  text  widdi  and  h^ght« 
starting  at  die  current  screen  location. 

Rc.geLte8tJboK  (text,  top,  bottom,  left,  right)  get  text  extents 

char  *text ; 

int  *top,  *bottom,  *left,  *right ; 

The  extent  of  the  area  enclosing  the  teact  is  returned  in  the  integer  pointers 
bottom^  IcA,  and  ri^ht  No  text  is  actually  drawa  This  is  useful  for  capturing 
the  text  extent  so  that  the  text  location  can  be  prepared  with  proper  bacl^routxl 
or  border. 


15.^.  User  Input 

The  raster  library  provides  mouse  (or  other  pointing  device)  irput  fiom  the  user.  I’his 
can  be  accomplished  with  a  pointer,  a  rubber-band  line  or  a  ndbber-barxl  box.  l^n 
pressing  one  of  three  mouse  buttons,  die  current  mouse  location  and  the  button  pressed 
are  returned. 

ILgeOocatiati_vritlL.painter  (nx,ny, button)  get  mouse  location  using  pointer 

int  *nx,  *ny,  *button  ; 

A  cursor  is  put  on  the  screen  at  the  location  specified  by  the  coordinate  found  at 
the  nx^iy  pointers.  'IHs  c'Jisor  tracks  the  mouse  (or  other  pointing  device)  until 
one  of  thr^  mouse  buttons  are  pressed.  Upon  pressing,  the  cursor  is  removed 
from  the  screen,  the  cunent  mouse  coordinates  are  returned  by  the  nx  and  ny 
pointers,  and  the  mouse  button  (1  for  left,  2  for  middle,  and  3  for  right)  is 
returned  in  the  button  pointer. 

R_getJocatiGn_withJnie  (x,y,nx,ry,button)  get  mouse  location  using  a  line 

intx,  y; 

int  *nx,  *rTy,  *button  ; 

Smilar  to  ILgetJxx:aiionjLuUh_pointeAp.  156)  except  the  pointer  is  replaced  by  a 
line  which  has  one  end  fixed  at  the  coordinate  identified  by  the  x,y  values.  The 
other  end  of  the  line  is  initialized  at  the  coordinate  identified  by  the 
pointers.  This  end  then  tracks  the  mouse  until  a  button  is  pressed.  The  mouse 
button  (1  for  left,  2  for  middle,  and  3  for  right)  is  returned  in  the  button  pointer. 
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R_£etJocati(Ml_witlL.ba8:  button)  get  nvuae  location  using  a  box 

intx,  y; 

int  *nx,  *ny,  *buttDn ; 

Identical  to  R_getJjocaiionjjuiihJineip.i56)  execpt  a  rubber-band  box  is  used 
instead  of  a  rubber-band  line. 


15.9.  Loadmg  the  Rastar  Grai^cs  lihra^ 

The  library  is  loaded  by  specifying  $(RA.SrERLIB)  in  the  Gmakefile.  The  following 
example  is  a  complete  Gmakefile  which  compiles  code  that  uses  this  library: 

_ Gmakefile  for  $(RAt>rfcIKI-JB) _ 

OBJ  =  maiao  subl.o  8ub2.o 

pgm  $(OBJ)  $(EASrERLIB)  $(GISLIB) 

$(CO  ${LDFIAGS)  -0  $@  $(OBJ)  SdlASTERUB)  $(GISLIB). 

$<KASTERLIB);  #  in  case  the  libraiy  changes 

$(GISiLJB): _ #  in  case  the  Ubraiy  changes 


Note  This  library  must  be  loaded  with  $(GISLIB)  since  it  uses  routines  from  that 
library.  See  §i2  GIS  library  [p.  63]  for  details  on  that  library'. 

This  library  is  irsually  loaded  with  the  DISPLAY UB).  See  §id  Display  Graphics 
Library  [p.  159}  for  details  on  that  library. 

See  §ii  CompUiag  GRASS  Fhvgrane  Using  Gmake  |p.55J  for  a  complete  discussion  of 
Gmakefiles. 
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Chaptar  16 

Display  Grai^iks  library 


I6.I4  Introduction 

This  library  provides  a  wide  assortment  of  higher  level  gr^hics  commands  which  in 
turn  use  the  gr^hics  raster  library  primitives.  It  is  highly  recommended  that  this 
section  be  used  to  understEmd  how  some  of  the  GRASS  3.0  graphics  commands 
operate.  Such  programs  like  Dvect,  Dgraph,  and  DceU  demonstrate  how  these  routines 
work  together.  The  routines  fall  into  four  basic  sets:  1)  window  creation  and 
management  2)  coordinate  conversion  reoutines,  3)  specialized  efficient  raster  displ^ 
routines,  and  4)  assorted  miscellaneous  routines  like  command  line  parsing  and  line 
clipping. 

Note.  All  routines  and  global  variables  in  this  library,  docirmented  or  undocumented, 
start  with  the  prefix  D_.  To  atvoid  name  conflicts,  programmers  should  not  create 
variables  or  routines  in  their  own  programs  which  use  this  prefix. 

An  alphabetic  index  is  provided  in  §24.5  Appendix  F.  Index  to  Display  Graphics 
library  [p.247\. 


16.2.  Window  Mane^ement 

The  followir^  set  of  routines  creates,  destroys,  and  otherwise  manages  graphics 
windows. 
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create  mw  graphics  window 


D_jiew_wiiidaw  (name,  top,  botbm,  left,  rights 
char  *name  ; 

int  top,  bottom,  left,  right ; 

(Creates  a  new  window  name  with  coordinates  top^  botton^  lefit,  and  li^it  If 
name  is  die  empty  string  ""  (i.e.,  *nanie  ==  0),  die  routine  returns  a  unique 
string  in  nama 

D_get_Clir_wind  (name)  set  current  graphics  window 

char  *name ; 

Selects  the  window  name  to  be  the  current  window.  The  previous  current 
window  (if  there  was  one)  is  outlined  in  grey.  The  selected  current  window  is 
outlined  in  white. 

D_get_CUr_wind  (name)  identify  current  graphics  window 

char  *name  ; 

C^tures  the  name  of  the  current  window  in  stiipg  nama 

D jshowLwindow  (color)  outlines  current  window 

int  color ; 

Outlines  cument  window  in  ookr.  Appropriate  colors  are  found  in 
$GISBASE/src/D/libes/colors.h^  and  are  spell^  widi  lower-case  letters. 

D  get  aorem  window  (top,  bottom,  left,  right)  retrieve  current  window  coordinates 

int  *top,  ^bottom,  *left,  *right ; 

Returns  current  window’ s  coordinates  in  the  pointers  top^  botton^  left,  and 

D_dieA_map_window  (window)  assignAetrieve  current  nop  window 

Struct  CelLhead  *window ; 

Graphics  windows  can  have  GRASS  map  windows  associated  with  them.  This 
routine  passes  the  window  to  the  current  gr^hics  window.  If  a  GRASS 
window  is  already  associated  with  the  gr^hics  window,  its  information  is  copied 
into  window  for  use  by  the  calling  program  Otherwise  window  is  associated 
with  the  current  graphics  window. 


^  $GISBASE  is  the  directoiy  where  GRASS  is  installed.  See  §I0.i  UNIX  Erivironment 
\p.5i]  for  details. 
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D_jresetJ9Creen_window  (top,  bottjOiD,  left,  ri^it)  resets  current  uindow  position 

int  top,  bottom,  left,  right ; 

Re-establishes  the  screen  position  of  a  window  at  tire  location  specified  by  top, 
botton^  kfi,  and  ri^it 

D_till]EStanf>  ( )  give  current  time  to  window 

'Hmestanp  the  current  window.  This  is  used  primarily  to  identify  which 
windows  are  on  top  of  which  others. 

D_€ra8e_willdow  (  )  erase  current  window 

Erases  the  window  on  screen  using  the  currently  selected  color. 

D_reniove_window  (  )  remove  a  window 

Remove  arty  trace  of  current  wmdow. 

D_dear_willdow  (  )  clears  information  about  current  window 

Removes  all  information  sfoout  current  window.  This  includes  the  map  window 
and  the  window  content  lists. 


16^.  Window  Contexts  Mans^^etne^ 

This  special  set  of  graphics  window  management  routines  maintains  lists  of  window 
contents. 


D_add^tQjist  (string)  add  command  to  window  display  list 

char  ^string  ; 

Adds  strir^  to  list  of  screen  conterrts.  By  convention,  string  is  a  command 
string  which  could  be  used  to  recreate  a  part  of  the  graphics  contents.  This 
should  be  done  for  all  screen  graphics  except  for  the  display  of  raster  (grid  cell) 
ma ' The  D_set_cell_name( )  routine  is  used  for  this  special  case. 
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D_j9etL0efljnBnie  (name)  add  cell  fUe  name  to  dH^iay  list 

char  *name ; 

Stores  the  cell  file  name  in  the  infonnadon  associated  with  the  cunent  window. 

D_getLcelLname  (name)  retrieve  cell  fUe  name 

char  *name ; 

Returns  the  name  of  the  cell  file  associated  with  the  current  window. 

D_dear_window  ( )  clear  window  di^)lay  lists 

Removes  all  display  information  lists  associated  with  the  current  window. 


16.4.  Coordiiiate  Transformation  Routmes 

These  routines  provide  coordinate  tiansfonnation  information  GRASS  graphics 
programs  typically  work  with  die  following  tiiree  coordinate  systems: 

Cooidinabe  system  Origin _ 

Di^ay  screen  ujqjer  left  (NW) 

Earth  window  lower  left  (SW) 

Array  window  upper  left  (NW) 


Display  screen  coordinates  are  the  physical  coordinates  of  the  display  screai  and  are 
referred  to  as  jc  and  y.  Earth  window  coordinates  are  from  the  GRASS  database 
windows  and  are  referred  to  as  east  and  north.  Array  coordinates  are  the  columns  and 
rows  relative  to  the  GRASS  window  and  are  referred  to  as  column  and  row. 

The  routine  D_do_conversions( )  is  called  to  establidi  the  relationships  between  these 
different  systems.  Then  a  wide  variety  of  accompanying  calls  provide  access  to 
conversion  factors  as  well  as  conversion  routines. 

D_do_oonversiflns  (window,  top,  bottom,  left,  right)  initialize  conversions 

struct  CelLhead  ^window ; 
int  top,  bottom,  right,  left ; 

The  relationship  between  the  earth  window  and  the  top^  bottom,  left,  and  ri^ 
screen  coordinates  is  established,  which  then  allows  conversions  between  aU  three 
coordinate  systems  to  be  performed. 

In  the  following  routines,  a  value  in  one  of  the  coordinate  systems  is  converted  to  the 
equivalent  value  in  a  different  coordinate  system.  The  routines  are  named  based  on 
the  coordinates  systems  involved.  Display  screen  coordinates  are  represented  by  d, 
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artay  coordinafces  by  a,  and  earth  coordinates  by  u  (wdnch  stands  for  UTM). 
double 

D_lL.tO_ajfCW  (north)  earth  to  array  (north) 

double  north ; 

Returns  a  row  value  in  the  array  coordinate  system  when  provided  tire 
corresponding  north  value  in  the  earth  coordinate  system. 

double 

D_lL.tO_a_COl  (east)  earth  to  array  (east) 

double  east ; 

Returns  a  column  value  in  the  array  coordinate  system  when  provided  die 
corresponding  east  value  in  the  earth  coordinate  system 

double 

D_a_tO_d-row  (row)  array  to  screen  (row) 

double  row ; 

Returns  a  y  value  in  the  screen  coordinate  system  when  provided  the 
corresponding  row  value  in  the  array  coordinate  system 

double 

D_a_tO_<Lod  (column)  array  to  screen  (colwm) 

double  column ; 

Returns  an  x  value  in  the  screen  coordinate  system  when  provided  the 
comesporxiing  odumn  value  in  the  array  coordinate  system 

double 

D_ll_tO_d-row  (north)  earth  to  screen  (north) 

double  north ; 

Returns  a  y  value  in  the  screen  coordinate  system  when  provided  the 
corresponding  north  value  in  the  earth  coordinate  system 
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double 

D_IL1q_cLooI  (east)  earth  to  screen  (east) 

doii)le  east ; 

Returns  an  x  value  in  the  screen  coordinate  system  when  provided  the 
corresponding  east  value  in  the  eatdi  coordinate  system 

double 

D_4_to_UU!tlw  (y)  screen  to  earth  (y) 

double  y ; 

Returns  a  north  value  in  the  earth  coordinate  system  when  provided  die 
corresponding  y  value  in  the  screen  coordinate  system 

double 

D_<Lto_iL.col.  (x)  screen  to  earth  (x) 

double  X ; 

Returns  an  east  value  in  the  earth  coordinate  system  when  provided  the 
corresponding  x  value  in  the  screen  coordinate  system 

double 

D_<l_tO_SLJOW  (y)  screen  to  array  (y) 

double  y  ; 

Returns  a  row  value  in  the  array  coordinate  system  when  provided  the 
corresponding  y  value  in  the  screen  coordinate  system 

double 

D_d_tO_SL.Col  (x)  screen  to  array  (x) 

double  X  ; 

Returns  a  column  value  in  the  array  coordinate  system  when  provided  the 
corresporxling  x  value  in  the  screen  coordinate  system 

If  the  above  routines  prove  too  inefficient,  the  programmer  can  examine  the  source 
code  for  these  routines  to  see  how  the  conversions  are  done  and  create  new  conversion 
routines. 


16.5.  Raster  Graphics 

The  display  of  raster  gr^hics  is  veiy  different  from  the  display  of  vector  graphics. 
While  vector  graphics  routines  can  efficiendy  make  use  of  worid  coordinates,  the 
efficient  rendering  of  raster  images  requires  the  programmer  to  work  within  the 
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cooidinate  system  of  the  graphics  device.  These  iDutuies  malcp  it  easy  to  do  just  that 
The  application  of  these  routines  may  be  in^)ected  in  such  commands  as  coniine  and 
weight  which,  under  the  user's  option,  di^ay  graphics  results  immediately  to  the 
screen 

D_odL.draiWJ9etiq>  (top,  bottom,  left,  prepare  for  raster  graphics 

int  top,  bottom,  left  hght ; 

The  raster  display  sii>system  establishes  conversion  parameters  based  on  die 
screen  extent  ddined  by  top^  bottcn^  left,  and  aU  of  which  are  obtainable 
{romD_get_screeruwinihiiip.  160)  for  the  cunent  window. 

D_draw_ceILrow  (row,  raster)  render  a  raster  row 

int  row ; 

CELL  *raster ; 

The  row  gives  the  map  array  row.  The  raster  array  provides  the  cat^ories  for 
each  map  grid  cell  in  that  row.  This  routine  is  called  consecutively  with  the 
information  necessary  to  draw  a  raster  image  hum  north  to  soudi  No  rows  can 
be  skipped.  All  screen  pixel  rows  which  represent  the  current  map  array  row  are 
rendered.  The  routine  returns  the  map  array  row  which  is  needed  to  draw  the 
next  screen  pixel  row. 

D_OWriay_odLjrow  (row,  raster)  render  a  raster  row  without  zeros 

int  row ; 

CELL  *raster ; 

Equivalent  to  D_draw_celLrow( )  except  that  locations  with  category  0  are  left 
untouched,  rather  than  beirrg  covered  with  the  color  for  category  0. 


16.6.  Window  Clippn^ 

This  section  describes  a  routine  which  is  quite  useful  in  many  settiiigs.  Window 
clipping  is  used  for  graphics  display  and  digitizing. 
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D_ci^  (s,  n,  w,  e,  X,  y,  c_j!c,  c_y)  clip  coordinates  to  uindow 

doidble  s,  n,  w,  e; 
double  *xl,  *yl,  *x2,  *y2  ; 

A  line  represented  by  the  cooidinates  xl^l  and  x2^  is  clipped  to  the  window 
defined  by  s  (soudi),  n  (noitb),  w  (west),  and  e  (east).  Note  that  the  following 
constraints  must  be  true: 

w  <  e 
s  <  n 

'Die  xl  and  x2  are  values  to  be  compared  to  w  and  a  The  yl  and  y2  are  values 
to  be  compared  to  s  and  n. 

The  xl  and  x2  values  returned  lie  between  w  and  a  The  yl  and  y2  values 
returned  lie  between  s  and  n. 


16.7.  Pop-iq)  Menus 

D_pQf]|]p  (bcolor,  tcolor,  dcolor,  top,  left,  size,  options)  pop-up  menu 

int  bcolor ; 
int  tcolor ; 
int  dcolor ; 
int  left,  top ; 
int  size  ; 
char  *options[  ]  ; 

This  routine  provides  a  pop-ip  type  menu  on  the  graphics  screen  For  examples 
of  how  to  use  this  routine  see  the  source  code  for  the  GRASS  3.0  display 
program.  2  The  bookr  specifies  die  background  color.  The  totter  is  the  text 
color.  The  dookr  specifies  the  color  of  tte  line  used  to  divide  the  menu  items. 
The  top  and  left  specify  the  placement  of  the  top  left  comer  of  the  menu  on  the 
screen  0,0  is  at  the  bottom  left  of  the  screen,  and  100,100  is  at  the  top  right 
The  size  of  the  text  is  given  as  a  percentage  of  the  vertical  size  of  the  screen 
The  options  arr^  is  a  NULL  terminated  array  of  character  strings.  The  first  is  a 
menu  tide  and  the  rest  are  the  menu  options  (i.e.,  options[0]  is  the  menu  tide,  and 
options!  1],  options[2],  etc.,  are  the  menu  options).  The  last  option  must  be  the 
NUI  pointer. 

The  coordinates  of  the  bottom  right  of  the  menu  are  calculated  based  on  the  top 
left  coordinates,  the  sizev  the  number  of  options,  and  the  longest  option  text 
length.  If  necessary,  the  menu  coordinates  are  adjusted  to  make  sure  the  menu  is 

^  Tilt*  source  code  lor  display  is  under  $GISBASEysrc/D/pit>g_inter/display. 
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onthe  screea 

D  jpopiqp( )  does  the  following; 

1  Current  screen  contents  under  the  menu  are  sasred. 

2  Area  is  blanked  with  the  background  color  and  fringed  with  the  text  color. 

3  Menu  options  are  drawn  usiiig  the  current  font 

4  User  uses  the  mouse  to  choose  the  desired  optioa 

5  Menu  is  erased  and  screen  is  restored  widi  the  original  contents. 

6  Nurrber  of  die  selected  option  is  returned  to  the  callirig  program 


16.8.  Cdors 

U—resetLCOlors  (colors)  set  colors  in  diver 

struct  Colors  *colors; 

Turns  color  information  provided  in  the  ooJcrs  structure  into  color  requests  to  the 
graphics  driver.  These  colors  are  for  raster  graphics,  not  lines  or  text  See 
^12.9.3  Cell  Color  ThtAe  \p.94]  for  GIS  Library  roudones  which  use  this  structure. 

D.translatCLOGlor  (name)  color  name  to  mmber 

char  *name ; 

Takes  a  color  icime  in  ascii  and  returns  the  color  number  for  that  color.  Returns 
0  if  color  is  not  knowa  The  color  number  returned  is  for  lines  and  text  not  raster 
grairfiics. 


16.9.  Ixiadiiig  the  Disfday  Gitipfaics 

The  library  is  loaded  by  speci^^ng  $(DISFLAYLIB),  $(RASTERLIB)  arxl  $(GISLIB) 
in  the  Gmakefile.  The  foUowirig  exarr^le  is  a  complete  Gmakefile  which  compiles 
code  that  uses  this  library: 
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_ Gmakeflle  for  $(DISH>AYT  JRi _ 

OBJ  =  main.0  euhl.o  8ii>2.o 

pgm:  $(OBJ)  $(DISF1AYIIB)  $(RASIERLIB)  $(GISLIB) 
$(CC)  $(LDFtAGS)  -0  $@  $(0EJ)  $(DISPLAYL1B)  \ 
$(RAjSr[mJB)  $(GBL[B) 

$(DISF1AYLIB):  *  in  case  libiaiy  changes 

$(BASrrERLIB):  *  in  case  the  libreoy  changes 

SiGTSFiTB): _  #  in  case  the  libraiy  changes 


Note.  This  library  uses  routines  in  $(RASTERLJB).  See  §i5  Raster  Graphics  Library 
\p.  147]  for  details  on  that  library.  Also  StRASTERLEB)  uses  routines  in  $(GISLIB). 
See  §12  GIS  Library  [p.  63]  for  details  on  that  library. 

See  §11  ConpUing  GRASS  Prograrrs  Using  Gmake  [p.55]  for  a  corrplete  discussion  of 
Gmakefiles. 
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Ch^jter  17 

Lode  library 


17.1.  Introduction 

This  libiaiy  provides  an  advisory  locku^g  mechanism.  It  is  based  on  ihe  idea  that  a 
process  will  write  a  process  id  into  a  file  to  create  the  lock,  and  subsequent  processes 
will  obey  the  lock  if  the  file  stiU  exists  and  the  process  whose  id  is  written  in  the  file 
is  still  running. 

17.2.  Lode  Routine  Synapses 

lod^_file  (file,  pid)  create  a  lock 

char  *file; 
intpid; 

This  routine  decides  if  the  lock  can  be  set  and,  if  so,  sets  the  lock.  If  fife  does 
not  exist,  the  lock  is  set  by  creatirig  the  file  and  writing  the  pid  (process  id)  into 
the  file  If  file  exists,  the  lock  may  still  be  active,  or  it  rtety  have  been 
abandoned.  To  determine  this,  an  integer  is  read  out  of  the  file.  'Hiis  integer  is 
taken  to  be  the  process  id  for  the  process  which  created  the  lock.  If  this  process  is 
still  running,  the  lock  is  stiU  active  and  the  lock  request  is  denied.  Otherwise  the 
lock  is  considered  to  have  been  abandoned,  and  the  lock  is  set  by  writing  tiie  pid 
into  the  file 

Return  codes: 

1  ok,  lock  request  was  successful 
0  sorry,  another  process  already  has  the  file  locked 
-1  error,  could  not  create  the  file 
-2  error,  could  not  read  the  file 
-3  error,  could  not  write  the  file 
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unlock-fite  (file)  rermve  a  lock 

char  *file; 

This  routine  releases  the  lock  by  unlinking  This  routine  does  NOT  check  to 
see  that  the  process  unlocking  the  file  is  the  one  which  created  the  lock.  The  file 
is  sinply  unlinked.  Ih)grams  should  of  coui%  unlock  the  lock  if  they  created  it 
(Note,  however,  that  tiie  mechanism  conectiy  handles  abandoned  locks.) 

Return  codes: 

1  ok.  lock  file  was  removed 
0  ok.  lock  file  was  never  there 
-1  error,  lock  file  remained  after  attempt  to  remove  it 


17^.  Use  and  UimtatioDS 

It  is  worth  noting  that  the  process  id  used  to  lock  the  file  does  not  have  to  be  the 
process  id  of  the  process  wMch  actually  creates  the  lock.  It  could  be  flie  process  id  of 
a  parent  process.  The  GRASS  start-up  shells,  for  example,  invoke  an  auxiliary 
"locking"  program  that  is  told  the  file  name  and  the  process  id  to  use.  The  startrl^) 
shells  sinply  use  a  hidden  file  in  the  user's  home  directory  as  the  lock  file,^  and  their 
own  process  id  as  the  locking  pid,  but  let  the  auxiliary  program  actually  do  the  locking 
(since  the  lock  must  be  done  by  a  program,  not  a  shell  script).  The  only  consideration 
is  that  the  parent  process  not  exit  and  abandon  the  lock 

Warning.  Locking  based  on  process  ids  requires  that  all  processes  which  access  the 
lock  file  run  on  the  same  cpa  It  will  not  work  urder  a  network  environment  since  a 
process  id  alone  (without  some  kind  of  host  identifier)  is  not  sufficient  to  identify  a 
process. 


17.4.  Loadii^  the  Lock  Library 

The  library  is  loaded  by  specifyirrg  $(LOCKLIB)  in  the  Gmakefile.  The  following 
example  is  a  complete  Gmakefile  which  corrpiles  code  that  uses  this  Library: 


'  This  file  is  .gislock  under  GRASS  3.0. 
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_ Gmakefile  for  $(LOCKT  iTR^ _ 

OBJ  =  maiao  sdbl.o  suib2.o 

pgnr  $(OBJ!)  $(LOCKLIB) 

$(CC)  $(LDFLAGS)  -o  $@  $(OBJ)  $(LOCKIJB) 

SGLOCKLIB):  *  in  case  the  libraiy  changes _ 


See  §22  CompUivg  GRASS  Programs  Using  Gmahe  \p.55]  for  a  conplete  discussion  of 
Gmakefiles. 
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Chapter  18 

Ro(do  Library 


18.1.  Introducticsi 

Sometimes  it  is  necessary  to  process  large  files  which  contain  data  in  a  matrix  format 
and  keep  more  than  one  row  of  the  data  in  memory  at  a  time.  For  exanple,  siqjpose  a 
program  were  required  to  look  at  five  rows  of  data  of  input  to  produce  one  row  of 
output  (neighborhood  function).  It  would  be  necessary  to  allocate  five  noemory  buffers, 
read  five  rows  of  data  into  tiiem,  and  process  the  data  in  the  five  buffers.  Then  the 
next  row  of  data  would  be  read  into  the  first  buffer,  overwriting  the  first  row,  and  the 
five  buffers  would  again  be  processed,  etc.  This  memory  management  conplicates  tiie 
programming  somewhat  and  is  peripheral  to  the  function  being  developed. 

The  Eoiiio  Library  routines  handle  this  memory  management  These  routines  need  to 
know  the  nurrber  of  rows  of  data  that  are  to  be  held  in  memory  and  how  many  bytes 
are  in  each  row.  They  must  be  given  a  file  descriptor  open  for  readirig.  In  order  to 
abstract  the  file  i/o  from  the  memory  management,  the  programmer  also  si5)plies  a 
subroutine  which  will  be  called  to  do  the  actual  readirig  of  the  file.  The  library 
routines  efficiently  see  to  it  that  the  rows  requested  by  the  program  are  in  memory. 

Also,  if  the  row  buffers  are  to  be  written  back  to  the  file,  there  is  a  mechanism  for 
handling  this  management  as  well. 

Note.  All  routines  and  global  variables  in  this  library,  documented  or  undocumented, 
start  with  the  prefix  rowio_.  To  avoid  name  conflicts,  programmers  should  not  create 
variables  or  routines  in  their  own  programs  which  use  this  prefix. 

An  alphabetic  index  is  provided  in  §24.5  Appendix  H.  Index  to  Bouio  Library  Ip. 252]. 
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18^.  Rowip  Routme  Slynapses 

The  routines  in  the  Rowio  library  are  described  below.  They  use  a  daota  stnicture 
called  ROWIO  which  is  defined  in  the  header  file  "rowioii"  tl^  must  be  included  in 
any  code  using  these  routines;^ 

#include  "rowio.h" 


rowio.j9etiq>  (r,  fd,  nrows,  len,  getrow,  putrow)  configure  rouio  structure 

ROWIO  *r, 
int  fd,  nrows,  len; 
int  (*getrow)( ); 
int  (*pulrow)( ); 

Rowio_settq)()  initializes  the  ROWIO  sttucture  r  and  allocales  the  required 
memory  bufifers.  The  file  descriptor  fd  must  be  open  for  reading.  The  nmn^  of 
rows  to  be  held  in  memory  is  nraws.  The  length  in  bytes  of  each  row  is  len. 
The  routine  which  will  be  called  to  read  data  from  the  file  is  getraw( )  and  must 
be  provided  by  tiie  programmer.  If  the  application  requires  that  the  rows  be 
written  back  into  the  file  if  changed,  the  file  descriptor  fd  must  be  open  for  write 
as  well,  and  the  programmer  must  provide  a  putrowt )  routine  to  write  the  data 
into  the  file.  If  no  writirig  of  the  file  is  to  occur,  specify  NULL  for  putraw< ). 

Return  codes: 

1  ok 

-1  there  is  not  enough  memory  for  buffer  allocation 


The  getrow< )  routine  will  be  called  as  follows: 

getrow  (fd,  buf,  n,  len) 

int  fd; 
char  *buf; 
int  n,  len; 


When  called,  getrowt )  should  read  data  for  row  n  from  file  descriptor  fd  into  buf 
for  len  bytes.  It  should  return  1  if  the  data  is  read  ok,  0  if  not 


The  putrow( )  routine  will  be  called  as  follows: 


’  Tlie  GRASS  compilation  process,  described  in  §/2  Conpiling  CSiASS  Prograne  Using 
Grnake  Ip.  55],  automadcally  tells  the  C  compiler  how  to  find  this  and  other  GRASS  header  files. 
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putiDw  (fd,  buf,  n,  len) 

intfd; 
char  *buf; 
intn,  len; 


When  called,  pulrow( )  should  write  data  for  row  n  to  file  descriptor  fd  from  buf 
for  len  bytes.  It  should  return  1  if  the  data  is  written  ok,  0  if  not 

char  * 

rOwiOLget  (r,  n)  read  a  row 

ROWIO  *r, 
int  n; 

Rowio_get( )  returns  a  bufiTer  which  holds  the  data  for  row  n  from  ttie  file 
associated  with  ROW^O  structure  r.  If  the  row  requested  is  not  in  memoiy,  the 
getrawO  routine  specified  in  rouio_setiq)(p.  174)  is  called  to  read  row  n  inlo 
memoiy  and  a  pointer  to  the  memoiy  buffer  containing  the  row  is  returned.  If 
the  data  currenliy  in  tiie  buffer  had  been  changed  by  ronio_put(p.l76),  the 
putrawO  routine  specified  in  rouio_setiq^.  174)  is  called  first  to  write  the 
changed  row  to  disk.  If  row  n  is  already  in  memoiy,  no  disk  read  is  done.  The 
pointer  to  the  data  is  simply  returned. 

Return  codes: 

NULL 


!NULL 


rowioLjforget  (r,  n) 

ROWIO  *r, 
intn; 

Rowio_ibiget( )  tells  the  routines  that  the  next  request  for  row  n  must  be  satisifed 
by  reading  the  file,  even  if  the  row  is  in  memoiy. 

For  example,  this  routine  should  be  called  if  the  buffer  returned  by 
rouio_ge1ip.l75)  is  later  modified  directly  without  also  writing  it  to  the  file.  See 
^18.3  Bouwo  Programring  Considerations  \p.l76\. 


n  is  n^alive,  or 

getrow( )  returned  0  (indicating  an  eiror  condition), 
pointer  to  buffer  containing  row  n. 


forget  a  low 
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rowiCLfloiO  (r)  get  fUe  (kscriftor 

ROWIO  ^r, 

Rowio jfiileno( )  I'Btums  tiie  file  descriptor  associated  with  die  ROWIO  structure. 

rovriOLrdease  (r)  free  allocated  wenory 

ROWIO  ♦r, 

Rowio_release( )  frees  all  the  memory  allocated  for  ROWIO  structure  r.  It  does 
not  close  die  file  descriptor  associated  with  the  structure. 

rowio_put  (r,  buf,  n)  write  a  row 

ROWIO  *r, 
char  *buf; 
intn; 

Rowio_put( )  writes  the  buffer  buf^  which  holds  the  data  for  row  n,  into  the 
ROWIO  structure  r.  If  the  row  requested  is  cunendy  in  memory,  the  buffer  is 
sinqily  copied  into  the  structure  and  marised  as  having  bear  changed.  It  will  be 
written  out  later.  Otherwise  it  is  vmtten  immediately.  Note  that  when  the  row  is 
finally  written  to  disk,  the  pttorawO  routine  specified  in  rouio_setup(p.  174)  is 
called  to  write  row  n  to  the  file. 

rowiojQush  (r)  force  pending  updates  to  disk 

ROWIO  *r, 

Rowiojflushf )  forces  all  rows  modified  by  rouio_put(p.  176)  to  be  written  to  the 
file.  This  routine  must  be  called  before  closiug  the  ffle  or  releasing  the  rowio 
structure  if  rowio_put( )  has  been  called. 


18^.  Rowio  FVograammig  ConsideratioDS 

If  the  contents  of  the  row  buffer  returned  by  rowio_get( )  are  modified,  the 
programmer  must  eitha"  write  the  modified  buffer  back  into  the  file  or  call 
rowio_foiget( ).  If  this  is  not  done,  the  data  for  the  row  will  not  be  correct  if 
requested  again  The  reason  is  that  if  die  row  is  still  in  memory  when  it  is  requested  a 
second  time,  the  new  data  will  be  returned.  If  it  isn’ t  in  memory,  the  file  wdl  be  read 
to  get  the  row  and  the  old  data  will  be  returned.  If  the  modified  row  data  is  written 
back  into  the  file,  these  routines  will  behave  correcdy  and  can  be  used  to  edit  files.  If 
it  is  not  written  back  into  the  file,  rowio_forget( )  must  be  called  to  force  the  row  to  be 
read  from  the  file  when  it  is  next  requested. 

Rowio_ged )  returns  NULL  if  getrow( )  returns  0  (indicating  an  error  readmg  the  file), 
or  if  the  row  requested  is  less  than  0.  The  c^ling  sequeixe  for  rowio_get( )  does  not 
permit  error  codes  to  be  returned.  If  error  codes  are  needed,  they  can  be  recorded  by 
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getrow( )  in  ^obal  variables  for  Ihe  rest  of  the  program  to  check 

18.4.  Loading  the  Roido  library 

The  library  is  loaded  by  specifying  $(ROWIOLIB)2  in  the  Gmakefile.  The  following 
example  is  a  complete  Gmakefile  which  cornices  code  drat  uses  this  library: 

_ Gnmkeffle  for  $(ROWIOLB) _ 

OBJ  =  maiao  subl.o  sub2.o 

pgm  $(OBJ)  $aiOWIOIJB) 

$(CC)  $(LDIIAGS)  -o  $@  $(OBJ)  $(ROWIOIJB) 

$(ROWIOLIB):  #  in  case  the  libraiy  changes _ 

See  §11  ConpUing  GRASS  Programs  Using  Gmahe  |p.55]  for  a  conaplete  discussion  of 
Gmakefiles. 


This  variable  was  NOT  defined  in  releases  3.0  and  3.0A.  Edit  the  file 
$Gi:^A3E/src/CMD/irvke.nid  and  aid  the  line  ROWIOLIBs$(LIBIXR)/ro«viaa  at  the 
bottom  of  the  file. 
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Chaptar  19 

Segment  library 


19.1.  Introduction 

Large  data  files  which  contEdn  data  in  a  matrix  format  often  need  to  be  accessed  in  a 
non-sequential  or  random  manner.  This  requirement  complicates  toe  programming. 
Methods  for  accessing  toe  data  ate  to: 

(1)  read  toe  entire  data  file  into  memoiy  and  process  toe  data  as  a  two- 
dimensional  matiix, 

(2)  perform  direct  sccess  i/o  to  toe  data  file  for  every  data  value  to  be  accessed, 
or 

(3)  read  only  portions  of  toe  data  file  into  memory  as  needed. 

Method  (1)  greatly  sinpliiies  toe  programming  effort  since  i/o  is  done  once  and  data 
access  is  simple  array  referetring-  However,  it  has  toe  disadvantage  that  large 
amounts  of  memory  may  be  reqirired  to  hold  toe  data  The  memory  may  not  be 
available,  or  if  it  is,  system  pagirrg  of  toe  program  may  severely  degrade  paformance. 
Method  (2)  is  not  much  mote  con^licated  to  code  and  requires  no  significant  amount 
of  memory  to  hold  toe  data  But  the  i/o  involved  will  certainly  degrade  performance. 
Method  (3)  is  a  mixture  of  (1)  and  (2).  Memory  requirements  ate  fixed  and  data  is 
read  from  toe  data  file  only  when  rx)t  already  in  memory.  However  the  programming 
is  more  complex. 

The  routines  provided  in  this  librEKy  are  an  implementation  of  method  (3).  They  are 
based  on  the  idea  that  if  the  original  matrix  were  segmented  or  partitioned  into  smaller 
matrices  these  segments  could  be  managed  to  reduce  both  the  memory  required  and 
the  i/o.  Data  access  alorig  connected  paths  through  the  matrix,  (i.e.,  moving  iq)  or 
down  one  row  and  left  or  right  one  column)  should  benefit 

In  most  applications,  the  original  data  is  not  in  the  segmented  format  The  data  must 
be  transformed  from  the  r»n-segmented  format  to  the  segmented  format  This  means 
reading  the  original  data  matrix  row  by  row  arxl  wntirig  each  row  to  a  new  file  with 
the  segmentation  organization  This  step  corresponds  to  the  i/o  step  of  method  (1). 
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Then  Hate  can  be  retrieved  finm  the  segment  file  throu^  routines  by  i^)ecifyiiig  die 
row  and  column  of  the  original  matrix.  Behind  the  scenes,  the  data  is  paged  intn 
memory  as  needed  and  the  requested  data  is  returned  to  die  caller. 

Ndta  AU  routines  and  global  variahles  in  this  library,  documented  or  undocumented, 
start  widi  the  prefix  s^mentL.  To  avoid  name  conflicts,  programmers  should  not 
create  variables  or  routines  in  their  own  programs  which  use  this  prefix. 

An  alphabetic  index  is  provided  in  ^24.5  Appendix  1.  Index  to  Segment  Library  [p.253]. 


19^.  Segment  Routmes 

The  routines  in  the  Segment  library  are  described  below,  more  or  less  in  the  order 
they  would  logically  be  used  in  a  program.  They  use  a  data  structure  called 
SEGMENT  which  is  defined  in  the  header  file  "segmenth"  that  must  be  included  in 
any  code  usir^g  these  routines:^ 

#include  "segmenth" 


The  first  step  is  to  create  a  file  which  is  properly  formatted  for  use  by  the  Segment 
Library  routines: 

segmenOormot  (fd,  nrows,  ncols,  stows,  scols,  len)  fbmat  a  segment  fUe 

int  fd,  nrows,  ncols,  stows,  scols,  len; 

The  s^mentation  routines  require  a  disk  file  to  be  used  for  paging  segments  in 
and  out  of  memory.  This  routine  formats  the  file  open  for  write  on  file  descriptor 
fd  for  use  as  a  segment  file.  A  segment  file  must  be  formatted  before  it  can  be 
processed  by  other  segment  routines.  The  configuration  parameters  nrows»  nools, 
STOWS,  sools^  and  len  are  written  to  the  b^uirdng  of  the  segment  file  which  is 
then  filled  with  zeros. 

The  corresponding  norr-segmented  data  matrix,  which  is  to  be  transferred  to  the 
segment  file,  is  nrows  by  nools.  The  s^ment  file  is  to  be  formed  of  segments 
which  are  atiws  by  soola  The  data  items  have  lerrgth  len  bytes.  For  example,  if 
the  data  type  is  int,  len  is  sizeofiint). 

Return  codes  are:  1  if  ok;  else  -1  could  not  seek  or  write  fd,  or  -3  illegal 
configuration  parameterfs). 

The  next  step  is  to  initialize  a  SEGMENT  structure  to  be  associated  with  a  segment 
file  formatted  by  segmentjormadp.  180). 

*  TlTe  GRASS  compilation  process,  described  in  §ii  Compiling  GRA^  Progmms  Using 
Gmahe  \p.  5S\,  automatically  tells  the  C  compiler  how  to  find  this  and  other  GRASS  header  files. 
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SCgDientJlltt  (S6g>  fdt  ns^s)  initialue  segrrent  stricture 

SEGMENT  *seg; 
intfd,  ns^; 

Initializes  the  seg  structure.  Ihe  file  on  fil  is  a  s^[ment  tile  created  by 
segrTKiUjormatip.  180)  and  must  be  open  for  reading  and  writing.  The  s^ment 
tile  configuration  parameters  nrows,  ncols,  srous,  scols,  and  len,  as  written  to 
the  file  by  segrmrtjbrrmtip.  180),  are  read  finm  the  file  and  stored  in  the  aeg 
structure.  Nsegs  specifies  the  number  of  s^ments  that  will  be  retained  in 
memoiy.  The  mini  mum  value  allowed  is  1. 

Note.  The  size  of  a  s^ment  is  scols*STX>ws*len  plus  a  few  bytes  for  managing 
each  segment 

Return  codes  are:  1  if  ok;  else  -1  could  not  seek  or  read  segment  file,  or  -2  out  of 
memory. 

Then  data  can  be  written  from  another  file  to  the  segment  file  row  by  row: 

segment_putjraw  (seg,  buf,  row)  write  row  to  segment  file 

SEGMENT  *seg; 
char  *buf; 
introw; 

Transfers  non-segmented  matrix  data,  row  by  row,  into  a  segment  file.  Seg  is  the 
segment  structure  that  was  configured  from  a  call  to  segrnentjmfip.  181).  Buf 
should  contain  rv:ols*len  bytes  of  data  to  be  transferred  to  the  segment  file.  Row 
specifies  tiie  row  from  the  data  matrix  beiiig  transferred. 

Return  codes  are:  1  if  ok;  else  -1  could  not  seek  or  write  segment  file. 

Then  data  can  be  read  or  written  to  (he  segment  file  randomly: 

segmoiL^et  ( seg,  value,  row,  col )  get  value  fi-om  segrrent  file 

SEGMENT  *seg; 
char  *value: 

Lnt  row,  col; 

Rnvides  rarxiom  read  access  to  the  segmented  data  It  gets  len  bytes  of  data  into 
value  from  the  segment  file  seg  for  the  correspondiig  row  and  col  in  the  original 
data  matrix. 

Return  codes  are:  1  if  ok;  el.se  -1  could  not  seek  or  read  segment  file. 
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segmoiiLpiil;  (seg,  value,  row,  col)  put  xxdue  to  segwert  file 

SEGMENT  *s^, 
char  *valtie; 
int  row,  col; 

Rovides  random  write  access  to  the  s^mented  data  It  copies  len  bytes  of  data 
horn  vahie  into  the  s^iment  structure  seg  for  the  corresponding  row  and  col  in 
the  original  data  matrix. 

The  data  is  not  written  to  disk  immediately.  It  is  stored  in  a  memory  s^rrient 
until  the  segment  routines  decide  to  page  the  segment  to  disk. 

Return  codes  are:  1  if  ok;  else  -1  could  not  seek  or  write  s^ment  file. 

After  random  reading  and  writirg  is  finished,  die  pending  iqxiates  must  be  flushed  to 
disk 

segmcnt-flush  (seg)  fbjsh pending  igidates  to  disk 

SEGMENT  *seg; 

Fbrces  all  pending  iplates  generated  by  segrmnt_piit{p.  182)  to  be  written  to  the 
s^ment  file  seg;  Must  be  called  after  the  final  segment_put( )  to  force  all 
pendiiig  iqxiates  to  disk  Must  also  be  called  before  the  first  caU  to 
segrmnt_get_rouip.  182). 

Now  the  data  in  s^ment  file  can  be  read  row  by  row  and  transferred  to  a  normal 
sequential  data  file: 

SegnieJlt_gEt_rOW  (seg,  buf,  row)  readwwfivm segment  file 

SEGMENT  *seg; 
char  *buf; 
int  row; 

lYansfers  data  from  a  s^ment  file,  row  by  row,  into  memory  (which  can  then  be 
written  to  a  r^ular  matrix  file).  Seg  is  the  segment  structure  that  was  configured 
from  a  call  to  segmentjmtip.  181).  Buf  will  be  filled  with  ncols*len  bytes  of  data 
correspondmg  to  die  row  in  the  data  matrix. 

Return  codes  are:  1  if  ok  else  -1  could  not  seek  or  read  segment  file. 

Finally,  memory  allocated  in  the  SEGMENT  structure  is  freed: 
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sq;il]enlLreiea9e  ( seg)  free  allocated  wemory 

SEGMENT  *seg; 

Releases  die  allocated  memoiy  associated  with  the  segment  file  aeg,  Does  not 
close  the  file.  Does  not  flush  flie  daia.  which  may  be  pending  from  previous 
segment_put(p.  182)  calls. 


19^  How  to  Use  the  Library  Routines 

The  following  should  provide  the  programmer  with  a  good  idea  of  how  to  use  the 
Segrmnt  library  routines.  The  exan^les  assume  that  tiie  data  is  integer.  The  first  step 
is  the  creation  and  formatting  of  a  s^ment  file.  A  file  is  created,  formatted  and  then 
closed; 


fd  =  creat  (file, 0666); 

segnient.forniat  (fd,  nrows,  ncols,  stows,  acols,  sizeoffinli)); 
cloae(fd) 


The  next  step  is  the  conversion  of  the  non-s^mented  matrix  data  into  s^ment  file 
format  The  segment  file  is  reopened  for  read  and  write,  initialized,  and  then  data  read 
row  by  row  from  the  original  data  file  and  put  into  the  s^ment  file: 

int  bxifTMXlLS]; 

SEGMENT  aeg; 

fd  =  open  (file,  2); 
aegnient_init  (&aeg,  fd,  nseg) 

for  (TOW  =  0;  TOW  <  nrows;  tow++) 

{ 

<code  to  get  original  matrix  data  for  row  into  biif> 
aegmenL-puLTOw  (&aeg,  buf,  row); 

} 

Of  course  if  the  intention  is  only  to  add  new  values  rather  than  iqxlate  existing  values, 
the  step  which  transfera  data  from  the  original  matrix  to  the  segment  file,  using 
segment_puLrow( ),  could  be  omitted,  since  segrmntJbrrmKp.  180)  will  fill  the 
segment  file  with  zeros. 

The  data  can  now  be  accessed  directly  using  segnierit_get{p.  181).  For  example,  to  get 
the  value  at  a  given  row  and  column: 
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intvdue; 


:<DeJvTii3' 


!^aeg; 


segmaiLget  (&aeg,  &valuB,  tow,  col); 

Stoilarly  segrnent_putip.  182)  can  be  used  to  change  data  values  in  the  segment  file: 


intvdue; 
SaSGcMENT  aeg; 


value  =  10; 

eegmenLput  (&seg,  &value,  row,  col); 

Waraini^  It  is  an  easy  mistake  to  pass  a  value  directly  to  segmenLputt ).  The 
following  should  be  avoided: 

segment-put  (&aeg,  10,  row,  col);  /*  this  mon’t  work  */ 

Once  the  random  access  processing  is  complete,  the  data  would  be  extracted  from  the 
s^ment  file  and  written  to  a  non-s^to^iented  matrix  data  file  as  follows: 

aegmentJliBh  (&seg); 

for  (row  =  0;  row  <  nrows;  row++) 

{ 

8^ment_get_row  (&aeg,  buf,  row); 

<code  to  put  bufisto  a  matrix  data  file  for  rouf> 

} 

finally,  the  memory  allocated  for  use  by  the  segment  routines  would  be  released  and 
the  file  closed: 

segment-release  (&8eg); 
close  (fd); 


Note.  The  Segment  Library  does  not  know  the  name  of  the  segment  file.  It  does  not 
attempt  to  remove  the  file.  If  the  file  is  only  teraporaty,  the  programmer  should  remove 
the  file  after  closii^  it 
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19.4  Ixiadiiig  tile  Segment  IJbraiy 

The  libiaiy  is  loaded  by  gpecifyiig  $(SEXjMENTLIB)  in  the  Gmakefile.  The  following 
example  is  a  con^ete  Gmakefile  which  compiles  code  fiiat  this  libiaiy: 


Gmakefile  for 


$(l 


mjB) 


OBJ  niain.0  subLo  sii)2.o 

pgm:  SfOBJD  $(SE)GMEISrrLIB) 

$((X!)  SOCnAGS)  -0  $@  $(080)  $(SBGMENrLIB) 

$(SEXjMENrLlB):  *  in  case  the  iibiaty  changes _ 


See  §22  CorvpUing  GRASS  Programs  Using  Gmahe  \p.55\  for  a  complete  discussion  of 
Gmakefiles. 
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ChaptGc20 

Vask  Library 


20.1.  Intixiduction 

The  Vask  Library  (visual-ask)  provides  an  ea^  means  to  communicate  with  a  user  one 
page  at  a  time.  That  is,  a  page  of  tejct  can  be  provided  to  die  user  with  information 
and  question  pron5)ts.  The  user  is  allowed  to  move  the  cursor^  from  prompt  to 
prompt  answering  questions  in  any  desired  order.  Users’  answers  are  confined  to  the 
programmer-specifi^l  screen  locations. 

This  interface  is  used  in  marry  interactive  GRASS  programs.^  For  the  user,  the  Vask 
Library  provides  a  very  consistent  and  siiEple  interface.  It  is  also  fairly  simple  and 
ea^  for  the  programmer  to  use. 

Note  All  routines  and  global  variables  in  this  library,  documented  or  urxiocumenled, 
start  with  die  prefix  V_.  To  avoid  name  conflicts,  programmers  should  not  create 
variables  or  routines  in  their  own  programs  which  use  this  prefix. 

An  alphabetic  index  is  provided  in  §24.5  Appendix  J.  Lndex  to  Vask  Library  \p.255]. 


20.2.  Vask  Routme  Slynopses 

The  routines  in  the  Vask  Library  are  described  below,  more  or  less  in  the  order  they 
would  logically  be  used  in  a  program  The  Vask  Library  maintains  a  private  data 
space  for  recording  the  screen  description  With  the  exception  of  V_call( ),  which  does 
all  the  screen  painting  and  user  interaction,  vask  routines  only  modify  the  screen 
description  and  do  not  update  the  screen  itself. 


^  The  fmctions  in  this  libray  make  use  of  the  curses  libraiy  and  termcap  descriptions.  As 
when  using  vi,  the  user  must  have  the  TERM  variable  set 
2  The  GRASS  window  command  is  a  good  example,  as  are  reclass  and  mask. 
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V_dcar  ( )  imtUdisx  screen  description 

This  routine  initializes  the  screen  description  information,  and  must  be  called 
before  each  new  screen  layout  description. 

VJfine  (num,  text)  cuid  line  of  text  to  screen 

int  num; 
char  *text; 

This  routine  is  used  to  place  lines  of  text  on  the  screen  Row  is  an  integer  value 
of  0-22  specifying  the  row  on  the  screen  where  the  text  is  placed  The  top  row 
on  the  screen  is  row  0. 

Warning  V_Jine( )  does  not  copy  the  text  to  the  screen  description  It  only  saves 
the  text  address.  This  implies  that  each  call  to  V_Jine( )  must  use  a  different  text 
buffer. 

V_00n8t  (value,  type,  row,  col,  len)  define  screen  constant 

V_ques  (value,  type,  row,  col,  len)  define  screen  question 

Ctype  *  value;  (Ctype  is  one  of  int,  long,  float,  double,  or  char) 

chET  type; 

int  row,  col,  len 

These  two  calls  use  the  same  syntax.  V_const( )  and  V_ques( )  specify  that  the 
contents  of  memory  at  the  address  of  vahie  are  to  be  displayed  on  the  screen  at 
location  row,  cd  for  kn.  characters.  V_ques( )  further  specifies  that  this  screen 
location  is  a  prompt  field  The  user  'vill  be  allowed  to  change  the  field  on  the 
screen  and  tiuis  change  the  vahie  itself.  V_const( )  does  not  define  a  prompt 
field  and  dius  the  user  will  not  be  able  to  change  these  values. 


Value  is  a  pointer  to  an  int,  long,  float,  double,  or  char  string.  Type  specifies 
what  type  value  points  to:  ’i’  (int),  T’  (long),  ’f  (float),  ’d’  (double),  or  ’s’ 
(character  string).  Row  is  an  integer  value  of  0-22  spec.'ying  the  row  on  the 
screen  where  the  value  is  placed.  The  top  row  on  the  screen  is  row  0.  Col  is  an 
integer  value  of  0-79  ^)ecifying  the  column  on  the  screen  where  the  value  is 
placed  The  leftmost  column  on  the  screen  is  column  0.  Len  specifies  the 
number  of  columns  that  the  value  will  use. 

Note  that  the  size  of  a  character  array  passed  to  V_ques( )  must  be  at  least  one 
byte  longer  than  the  length  of  the  prompt  field  to  allow  for  NULL  termination. 

(Currently,  you  are  limited  to  20  constants  and  80  variables. 

Warning  These  routines  store  the  address  of  vsdue  and  not  the  value  itself. 
This  implies  that  different  variables  must  be  used  for  different  calls. 
Programmers  will  instinctively  use  different  variables  with  V_  ),  but  it  is  a 
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stumbling  block  for  V_const( ).  Also,  the  programmer  mu^  initialize  valae  prior 
to  calling  tiiese  routines.^ 

VJtoaLaoCuracy  (num)  set  nunber  ofdecirml  places 

int  num; 

VJloat_accuracy( )  defines  the  number  of  decimal  places  in  which  floats  and 
doidbles  are  displayed  or  accepted.  ^ftIm  is  an  integer  value  definipg  the  number 
of  decimal  places  to  be  used.  This  routine  affects  subsequent  calls  to  V_const( ) 
and  V_ques( ).  Various  inputs  or  displayed  constants  can  be  leprosented  with 
different  numbers  of  decimal  places  within  flie  same  screen  displ^  by  makipg 
different  calls  to  V_floaLaccuracy( )  before  calls  to  V_ques( )  or  V_const( ). 
V_clear( )  resets  the  number  of  decimal  places  to  2. 

V.csaUO  interact  uith  the  user 

V_call()  cleats  the  screen  and  writes  flie  text  and  data  values  specified  by 
V_line( ),  V_ques( )  and  V_const( )  to  the  screen.  It  interfaces  with  the  user, 
collecting  user  responses  in  the  V_ques( )  fields  until  the  user  is  satisfied.  A 
message  is  automatically  si^plied  on  line  number  23,  explaming  to  the  user  to 
enter  an  ESC  when  all  inputs  have  been  supplied  as  desired.  V_call( )  aids  when 
the  user  hits  ESC  and  returns  a  value  of  1  (but  see  V_intipt_ok( )  below). 

No  error  checking  is  done  by  V_caQ( ).  Instead,  all  variables  used  in  V_ques( ) 
calls  must  be  checked  ipon  return  from  V_call().  If  the  user  has  si^tplied 
inappropriate  information,  the  user  can  be  informed,  and  the  ii:q[)ut  prompted  for 
again  by  further  calls  to  V_call( ). 

VJiitrpt_<ik  ( )  allow  ctrl-c 

V_call( )  normally  only  allows  the  ESC  character  to  end  the  interactive  input 
session  Sometimes  it  is  desirable  to  dlow  the  user  to  cancel  the  session  To 
provide  this  alternate  means  of  exit,  the  programmer  can  call  Vjntipt_ok() 
before  V_call( ).  This  allows  the  user  to  enter  Ctri-C,  which  causes  V_call( )  to 
return  a  value  of  0  instead  of  1. 

A  message  is  automatically  siq)plied  to  the  user  on  line  23  saying  to  use  Ctd-C  to 
cancel  the  input  session  The  normal  message  accompanying  V_call( )  is  moved 
up  to  line  22. 

Note,  When  V_jntipt_ok( )  is  called,  the  programmer  must  limit  the  use  of 
VJine( ),  V_ques( ),  and  V_const( )  to  lines  0-21. 


Technically  value  needs  to  be  initialized  before  the  call  to  V_call( )  since  V_con6t< )  and 
V_ques{ )  only  store  the  address  of  vahie  V_caU( )  looks  up  the  values  aid  places  them  on  the 
acneea 
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VJbltiptJtlElir  (text)  change  ctrl-c  message 

char  *text; 

A  call  to  VJntiptjBsgO  changes  the  default  VJntrpLokO  message  from 
(OR  <Ctii-C>  TO  CANCEL)  to  (OR  <(^-0  TO  msg).  The  message  is  (re)set 
to  the  default  by  V_cleai< ). 


20^.  An  Example  Rrogram 

Following  is  the  code  for  a  single  program  which  will  prompt  the  user  to  enter  an 
integer,  a  floatiiig  point  number,  and  a  character  string. 


^define  LEN  15 
tmn( ) 

{ 


inti  ; 
float  f ; 
charsfLEN]  ; 

/*  the  vatiables  */ 

i  =  0; 

1*  initialize  the  variables  */ 

f  =  0.0  ; 

*s  =  0 ; 

V_clear< ) ; 

/*  clear  vaek  info  */ 

V_line(  5,  "  Ebler  an  Integer ")  ; 

V_line(  7, "  Ehter  a  Decimal  ")  ; 

V_line(  9, "  Ehler  a  character  stiing  ")  ; 

/*  the  text  */ 

V'_ques  (  &d,  ’i’,  5,  30,  5)  ; 

V_ques(&f,  T,7,  30,  5)  ; 

V_ques  (  s,  V ,  9,  30,  LEIN  -  1)  ; 

/*  the  [xompt  fields  */ 

VJntrpt_ok( ); 

/*  dlow  ctri-c  */ 

if  (!V_call( )) 

/*  displa^y^  and  get  user  input  */ 

exittl); 

/*  exit  if  ctri-c  */ 

printf  ( "%d  %f  %s\n",  i,  f ,  s)  ; 

/*  ESC,  so  print  results  */ 

exittO); 

} 

The  user  is  presented  with  the  following  screen: 
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Ehter  an  bteger 

0 _ 

Ehter  a  Decimd 

0.00_ 

Ebter  a  character  string 

AFim  (X)MPLE^^^G  AIX  ANSWERS,  HIT  <ES(>  TO  CONTINUE 

(OR  <Ctii-C>  TO  CANCEL) 

The  user  has  several  options. 


<CR> 

CTRL-K 

CTRI^H 

CTRl^L 

CTRI^A 

ESC 

CTRI^C 


moves  the  cursor  to  the  next  prompt  field 

moves  the  cursor  to  tiie  previous  prompt  field 

moves  the  cursor  backward  nomdestruclively  within  the  field 

moves  the  cursor  forward  non-destructively  widin  the  field 

writes  a  copy  of  the  scre«i  to  a  file  named  lisual^ask  in  the  user's 
home  directory. 

returns  control  to  the  calling  program  with  a  return  value  of  1. 
returns  control  to  the  calling  program  with  a  return  value  of  0. 


Di^layable  ascii  characters  typed  by  the  user  are  accepted  and  displayed 
Control  characters  (other  than  those  with  special  meanirpg  listed  above)  are 
ignored 


20.4.  Ixiadiiig  the  Vask  library 

Compilations  must  specify  (he  vask,  curses,  and  termcap  libraries.  The  libraiy  is 
load^  by  specifying  $(VASK)  and  $(VASiKLIB)  in  the  Gmakefile.  The  following 
example  is  a  cortplete  Gmakefile  which  compiles  code  that  uses  this  library: 
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_ Gmakefile  for  $(VASK) 

OBJ  =  meiao  aisl.o  6ii)2.o 


-  192- 


pgm:  $(OBJ)  $(VASKIiB) 

$(CO  SODFLAGS)  -o  $@  $(OBJ)  $(VASK) 

SCVASKUB):  *  in  case  the  library  changes _ 

Note  The  target  pgm  depends  on  the  object  files  $(OBJ)  and  the  Vask  library 
$(VASKLIB).  This  is  done  so  that  modifications  to  any  of  the  $(OBJ)  files  or  to  the 
$(VASKIJB)  itself  will  force  program  reloading.  However,  the  compile  rule  specifies 
$(OBJ)  and  $(VASK),  rather  than  $(OBJ)  and  $(VASKLIB).  This  is  because 
$(VASK)  ^recifies  both  the  UNIX  curses  and  tenncap  libraries  as  well  as 
$(VASKLIB). 

See  §22  CoTrpUing  GRASS  Programs  Using  Gmahe  [p.55]  for  a  complete  discussion  of 
Gmakefiles. 


20^.  IVogramming  Ccnsaderations 

The  order  of  movement  from  pronqit  field  to  prompt  field  is  dependent  on  the  ordering 
of  calls  to  V_ques( ),  not  on  die  line  numbers  used  within  each  call. 

Information  cannot  be  entered  beyond  the  edges  of  the  prompt  fields.  Thus,  the  user 
response  is  limited  by  the  number  of  spaces  in  the  prompt  field  provided  in  the  call  to 
V_ques( ).  Some  interpretation  of  input  occurs  during  the  interactive  information 
gathering  session  When  the  user  enters  <CR>  to  move  to  the  next  prompt  field,  the 
contents  of  the  current  field  are  read  and  rewritten  accordiiig  to  the  value  type 
associated  with  the  field.  For  example,  tx)n-numeric  reqionses  (e.g.,  "abc")  in  an 
integer  field  will  get  turned  to  a  0,  arri  floating  point  numbers  will  be  truncated  (e.g., 
54.87  will  become  54). 

No  error  checking  (other  than  matching  irput  with  variable  type  for  that  input  field)  is 
done  by  V_call( ).  This  must  be  done,  by  the  programmer,  ipon  return  from  V_call( ). 

Calls  to  VJine( ),  V_ques( ),  and  V_const( )  store  only  pointers,  not  contents  of 
memory.  At  the  time  of  the  call  to  V_call( ),  the  contents  of  memory  at  these 
addresses  are  copied  into  the  sppropriate  places  of  the  screen  description  Cane  should 
be  taken  to  use  distinct  pointers  for  different  fields  and  lines  of  text  For  example,  the 
followirg  mistake  should  be  avoided: 
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char  textllOO]; 

V_clear(); 

qaintflteact,"  Welcome  to  GRASS  "); 

VJine{3,tBxO; 

qHinif(text,"  which  is  a  product  of  the  US  Am^  CEEiL  "); 
VJine(5,tBxt); 

V.caUO; 


since  this  results  in  die  followii^g  (urnntended)  %ieen: 


vthich  is  a  product  of  the  US  Am^  CEEtL 
which  is  a  product  of  the  US  Anny  CERL 


AFTER  COMPLETING  ALL  ANSWERS,  HIT  <ESC>  TO  CONTINUE 
(OR  <Ctri-C>  TO  CANCEL) 


Waarnng^  Due  to  a  problem  in  a  routine  within  the  curses  library,'^  the  Vask  routines 
use  the  curses  library  in  a  somewhat  unorthodox  way.  This  avoided  the  problem 
within  curses,  but  means  that  the  progrartiner  cannot  mix  the  use  of  the  Vask  Library 
with  direct  calls  to  curses  routines.  Any  program  isiiig  the  Vask  Library  should  not 
cdl  curses  Ubraiy  routines  Greedy. 


Specifically,  memoiy  allocated  by  initscK )  was  not  freed  by  endwin( ). 
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Cl]^]tiar21 

Writmg  a  DigUizar  Driver 


21.1.  Introduction 

A  digitizer  device  driver  consists  of  a  library  of  device-dependent  functions  that  are 
linked  into  digitizer  programs,  lliis  chapter  describes  those  functions  that  are  needed 
to  create  a  digitizer  device  driver  conqratible  with  GRASS  map  development  software. 

Section  ^212  Writing  the  Digitizer  Device  Driver  (p.  295]  explains  how  digitizer  drivers 
are  written,  while  section  §27.5  Discussion  of  the  Finer  Points  (Mnts)  \p.203]  describes 
problems  and  pitfalls  encountered  during  tiie  development  of  the  Altek  driver. 


21.2.  Writing  the  Digitizer  Device  Driver 

Source  code  for  the  digitizer  drivers  is  kept  in 
$GISBASEysrc/mapdev/digitizers^ 

Separate  sito-directories  contain  the  individual  drivers.  When  a  new  driver  is  written, 
it  should  be  placed  here  in  a  new  sub-directory. 

It  is  helpful  to  examine  the  source  code  for  existing  drivers  located  here,  and  to  attend 
a  demonstration  of  the  GRASS  digitizuig  program  digit,  before  developing  a  new 
driver. 


21.2.1.  Functions  to  be  Written 

This  section  describes  the  device-dependent  library  fuixtions  that  must  be  writtea 
Each  of  these  functions  must  be  present  in  the  library.  Rmetion  descriptions  are 
organized  by  file  name.  (The  file  names  are  those  used  by  current  GRASS  digitize 
drivers.  File  names  are  printed  in  bold,  along  the  left-hand  margin  of  tiie  page.)  These 

'  $GISBASE  is  the  directoiy  where  GRASS  is  installed.  See  §20.2  UNIX  EiiviroTvrent 
Ip.  SI]  for  details. 
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files  and  fimctions  can  be  copied  from  one  of  the  exMng  digitiza:  dnver  libimes  and 
altered  to  suit  the  needs  of  a  particular  diiver. 

Nola  Althou^  it  is  strongly  recommended  that  die  programmer  use  the  file  names 
listed  below  (for  reasons  set  forth  in  ^21^.3  ConpUing  the  Device  Driver  {p.202\), 
other  files  names  may  be  used  instead. 

digjmeniili 

This  file  contains  the  menu  that  is  displayed  while  digitizing.  The  menu  should 
indicate  the  purpose  of  the  buttons  on  the  cursor  for  the  particular  digitizer.  The 
menu  is  stored  in  dig  mmnr 

char  *dig_menu[  ] ; 

An  example  of  how  the  Altek  driver  uses  this  function  to  create  a  menu  is  given 
below: 

♦define  dig_menu_Iines  16 


char  *dig_menu[  ]  =  { 

"  GaEtASS-DICar  Voson  3.0  Digitizing  menu 


ALTEK  digitizar 

Cursor  kess 
<(]t>  di^tize  point 
<1>  qiitdii^tizing 

<2>  lydate  mflitnr 

<3>  togi^  point/straBm  mode 

AMOUNT  DICanZED 

♦  lines: 

♦  Area  edges: 

Ibtal  points 

CURRENT  DIGmZER  PARAM& 

MODE  TYRE 

point  line 

stream  areaedge 

} ; 

Note.  The  menu  must  be  exactiy  as  it  appears  here,  except  that  the  text  in  bold 
may  be  replaced  by  the  appropriate  text  for  the  digitizer. 

(fig_ci]r9e&c 

This  file  only  contains  #iix:ludes.  It  is  used  to  set  iqp  the  digitizing  menu  in  the 
"dig_jnenu.h"  file.  This  file  must  look  like  this: 
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#incliile  <ciiBeah> 

#include  "dig_menuJi" 
#include  "../../digit/digith" 
#include  "../../digit/inenuii" 
#inclxide  "../../Ubeadieadii" 

#include  "../../digit/curae8.c" 


seti:^driver.c 

D_sett5)_driver  (device) 
clar  *device ; 

This  function  opens  the  device  (which  is  a  tty  port)  and  initializes  the  digitizer. 

Note.  This  function  should  not  set  the  origin.  The  origin  is  set  later  by  the 
function  D_setup_oTiginip.  199). 

dig_dev.c 

D_get_scale(  scale) 
float  *scale ; 

This  function  sets  scale  to  the  digitizer  resolution  in  units  of  lines  per  inch^  For 
exanople,  on  a  digitizer  having  a  resolution  of  1000  lines  per  inch,  scale  would  be 
set  to  .001. 

ooOLpt&c 

#  include  "digit  h" 

^include  "globals.h" 

collect-points  (nxde,  type,  np,  x,  y) 
int  mode,  type ; 
int  *np  ; 

double  **x,  **y ; 

This  routine  is  called  to  collect  points  that  represent  a  sipgle  vector  (or  arc)  from 
the  digitizer. 

The  points  should  be  collected  into  static  arrays  or  dynamically  allocated  arrays, 
transfomaed  from  digitizer  cooidinates  to  database  coordinates  uang 
trxinsform_aj,rao_b(p.201),  and  plotted  on  the  graphics  monitor  ising 
plot^intsip.201).  Then  x  and  y  are  set  to  point  to  these  arrays,  and  np  set  to 
the  number  of  points  collected. 

Almost  all  digitizers  describe  their  resolution  in  lines  per  inch  dpi).  This  is  essentially 
equivalent  to  pixels  per  inch,  or  dots  per  inch. 
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llie  digitizing  mode  may  be  either  STEIEAM  or  POINT:  STREAM  indicates  that 
the  digitizer  should  collect  a  continuous  stream  of  points;  POINT  indicates  that 
the  digitizer  should  collect  points  under  user  control  (i.e.,  each  time  the  user 
presses  a  button,  the  foot-switch,  or  a  key  on  the  keyboard).  The  coUect_poinis  ( ) 
function  can  be  written  to  allow  interactive  togglii^  between  the  two  modes 
during  a  single  call. 

The  type  is  set  to  AREA  when  the  vector  to  be  collected  is  an  area  edge,  and  to 
LINE  when  it  is  is  a  linear  feature.  The  type  is  of  no  interest  to  coUect_poiitsi ) 
itself,  but  is  passed  to  the  function plot_points(p.20l),  which  draws  lines  on  the 
graphics  monitor. 

This  function  should  return  1  if  digitizir^g  in  STREAM  mode  occurred  (i.e.,  either 
becai^  mode  was  initially  STREAM,  or  because  the  user  changed  to  STREAM 
mode),  and  0  otherwise.^ 

Note.  This  routine  is  responsible  for  plotting  the  vector  on  the  graphics  monitor, 
but  it  should  do  it  responsibly.  This  means  that  while  digitizing  in  POINT  mode, 
the  line-segments  should  be  plotted  immediately;  while  digitizing  in  STREAM 
mode,  the  points  should  be  plotted  only  when  the  digitizing  is  finished,  or  when 
tihe  user  toggles  to  POINT  mode. 

Note  If  the  cursor  has  buttons,  they  can  be  used  to  chapge  the  digitizing  mode 
as  well  as  end  the  digitizir^.  If  the  digitizer  has  a  foot-switch  instead  of  buttons, 
the  foot-switch  should  be  used  to  end  die  digitizing  (toggling  modes  would  not  be 
sipported  in  this  case).  If  the  digitizer  has  neither  buttons  nor  a  foot-switch,  then 
tile  keyboard  must  be  used,  even  in  STREAM  mode.  (See  (jeoGraphics  driver  for 
code  that  polls  the  keyboard.) 

inler£aoe.c 

This  file  contains  a  number  of  functions.  The  following  functions  return 
information  about  digitizer  capabilities; 

D_cursorJbuttons( ) 

If  the  digitizer  cursor  buttons  are  to  be  used  by  the  digitizing  programs, 
there  must  be  at  least  five  buttons.  This  function  returns  1  if  the  cursor  has 
five  or  more  buttons;  otherwise,  it  returns  0. 

D_foot_switoh( ) 

This  function  returns  1  if  there  is  a  usable  footrswitch  It  returns  0  if  the 
digitizer  has  no  foot-switch 

Note  If  there  are  five  or  more  buttons  on  the  cursor,  the  value  returned  by 
STREAM  mode  indicates  to  digit  that  the  resulting  vector  should  be  pruned. 
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DJbot^uitchi )  is  ignored  (i.e.,  it  is  assumed  that  there  is  no  foot-switch). 
See  Dj:ursor_buttorts(p.  196). 

D_start_buttDn( ) 

This  function  tells  the  driver  how  the  cursor  buttons  are  labeled  (i.e.,  the 
labels  that  die  us^  sees  on  the  buttons).  If  the  first  button  is  labeled  1,  then 
this  routine  returns  1.  If  the  first  button  is  labeled  0,  then  this  routine  returns 
0. 

It  should  return  -1  if  the  digitizer  cursor  buttons  are  not  being  used  by  the 
driver.  See  D_citrsorjbitttons(p.  198). 

For  example,  if  die  digitizer  buttons  are  labeled  0-9,  then  this  routine  would 
return  0.  If  the  digitizer  buttons  are  labeled  1-16,  then  this  routine  would 
return  1. 


The  following  routines  perform  digitizer  configuratioir 
D_sett5)_origin( ) 

This  routine  sets  the  digitizer's  origin  (0,0).  This  routine  should  only  return 
if  successful,  and  should  return  a  value  of  0.  If  it  fails,  an  error  message 
should  be  sent  to  the  terminal  screen  with  Write  Jrrfbip.202),  and  the  program 
terminated  with  a  call  to  closejdownip.201). 

Note  Frequently,  the  location  of  the  digitizer' s  origin  can  be  set  to  some 
default  value,  without  arty  input  from  the  user.  Otherwise,  this  routine  must 
ask  the  user  to  set  the  origin  The  routine  Write  Jj^bip.  202)  should  be  used 
to  print  instructions  for  the  user.  (Refer  to  the  (jeotjraphics  digitizer  driver, 
which  instructs  users  to  set  the  origin  in  the  lower-left  comer  of  the 
digitizing  tablet)^ 

D_clear_driver( ) 

This  function  cleats  any  button  presses  on  the  digitizer  that  have  been 
queued.  (Refer  to  §22.5  Discussion  of  the  Finer  Points  (F&nts)  \p.203]  for  an 
explanation  of  why  this  is  necessary.)  This  routine  should  only  return  if 
successful,  and  should  return  a  value  of  0.  If  it  fails,  an  error  message 
should  be  sent  to  the  user  with  WrUeJ,nfb{p.202),  and  the  program 
terminated  with  a  call  to  close _douw^p.201). 


*  Due  to  the  design  of  the  GeoGraphics  digitizer,  it  isn’t  posable  to  detect  whether  or  not 
the  user  properly  sets  the  origin.  If  the  origin  is  irrproperly  set,  the  map  will  be  improperly 
registered. 
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The  following  two  routines  read  the  current  digitizer  coordinates: 

DjnatLraw  (x,  y) 
double  *x,  *y ; 

Gets  the  cunent  location  of  the  digitizer  cursor,  and  places  the  digitizer 
coordinates  in  the  variables  x  and  y. 

If  a  digitizer  button  was  pressed,  this  routine  returns  the  button’ s  value.  The 
return  value  must  be  in  the  range  of  1  throu^  16.  This  means  that  if  the 
first  button  is  labeled  0  this  routine  must  add  1  to  ttie  button  number  that  is 
returned. 

If  no  button  was  pressed,  this  routine  returns  0. 

Footrswitch.  If  the  digitizer  has  a  foot-switch,  instead  of  cursor  buttons, 
then  the  foot-switch  must  be  treated  as  if  it  were  button  1.  If  the  digitizer 
has  neither  a  foot-switch  nor  cursor  bitttons,  then  this  routine  should  return 
0. 

D_ask_driver_jaw  (x,  y) 
double  *x,  *y ; 

Waits  for  a  button  to  be  pressed  and  then  gets  the  cunent  location  of  the 
digitizer  cursor,  and  places  the  digitizer  coordinates  in  the  variables  x  and  y. 

This  routine  returns  the  button’s  value.  The  return  value  must  be  in  the 
range  of  1  through  16.  This  means  that  if  the  fust  button  is  labeled  0  this 
routine  must  add  1  to  the  button  number  that  is  returned. 

Foot-switeh.  If  the  digitizer  has  a  foot-switch,  instead  of  cirtsor  buttons, 
then  the  foot-switch  must  be  treated  as  if  it  were  button  1,  and  this  routine 
should  wait  for  the  foot-switch  to  be  pressed.  If  the  digitizer  has  neither  a 
foot-switch  nor  cursor  buttons,  then  this  routine  should  return  0  uithoict 
waiting. 

21.2,2.  Functions  AvailaUe  For  Use 

There  are  furxtions  which  have  already  been  written  that  can  be  called  by  the  digitizer 
driver.  These  are  described  below. 

Note.  These  fimctions  exist  in  libraries.  The  libraries  that  contain  these  functions  are 
described  in  ^21.2.3  CorrpUing  the  Device  Driver  \p.20Z\. 
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close_down  (status) 
int  status ; 

This  function  gracefully  exits  the  calling  program  Call  this  function  with  status 
set  to  -1  when  an  irrecoverable  error  has  occuned  (e.g.,  when  the  digitizer  does 
ix)t  respond,  or  returns  an  eroor).  Otherwise,  call  this  routine  with  status  set  to  0. 

plot_points  (type,  np,  x,  y,  line_color,  poinLcolor) 
int  type,  np; 
double  *x,  *y ; 
int  line_color,  poinLcolor ; 

This  function  is  to  be  called  by  collect_poinis(p.  197).  It  draws  the  vector  defined 
by  the  points  in  the  x  and  y  arrays  on  the  graphics  monitor.  The  nunher  of 
points  in  the  vector  is  npt 

The  plot_points  ( )  function  expects  to  receive  points  from  collect_points(p.  197)  in 
the  coordinate  ^stem  of  the  dat^ase.  Digitizer  coordinates  can  be  translated  to 
database  coordinates  using  tnimfbrrri_aJMo_Hp.20i). 

The  type  indicates  whether  the  vector  is  an  AREA,  or  a  LENR  AREA  and  LINE 
are  defined  in  the  include  file  "dig_defines.h". 

The  liiie_0(iflr  and  poinLoolor  indicate  whether  the  lines  and  points  are  to  be 
highlighted  or  erased  The  constant  CLR_HIGHLIGHr  indicates  highlighting, 
and  the  constant  CliURAiSE  indicates  erase  (CLR-HIGHLIGHr  and 
CRL_ERASE  are  defined  in  "globals.h").  The  colors  actually  used  to  highlight  or 
to  erase  lines  and  points  are  specified  by  the  user  in  digit. 

transfornx_aLinto_b  (Xraw,  Yraw,  X,  Y) 
double  Xraw,  Yraw  ; 
double  *X,  *Y  ; 

This  function  converts  the  digitizer  coordinates  Xraw,Yraw  into  the  database 
coordinates  X,Y.  This  function  is  used  by  the  driver  function 
collect_points(p.  197). 

Note.  The  transformation  rule  used  by  this  routine  is  generated  by  digit  when  the 
user  registers  the  map  to  the  database.  The  rule  is  already  in  place  by  the  time 
collect_points(p.  197)  calls  tramforrnjiJ,iTto_b{ ). 
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WntELinfo  Gine,  message) 
intline ; 
char  *message ; 

This  fuiKtion  prints  a  message  in  the  four  line  window  at  the  bottom  of  the 
user's  terminal  in  digit.  Hie  variable  liiie  must  be  a  number  1  tfarou^  4,  which 
represents  the  line  number  inside  the  window.  The  message  must  not  exceed  76 
characters  and  should  not  contain  \a 


21.2^  ConiBling  the  I)e\ioe  Driver 

Rograms  (e.g.,  digit)  that  use  die  digitizer  driver  functions  are  stored  in  libraries. 
When  the  digitizer  driver  is  con^iiled,  it  links  with  those  different  libraries  and  creates 
the  programs.  Each  driver  should  contain  a  Gmakefile  that  contains  compilation 
instructions  for  Grmke.^  The  Gmakefile  for  the  digitizer  driver  is  complex.  Rather 
than  attenpting  to  construct  a  con^iletely  new  Gmakefile,  it  is  generally  simpler  to 
copy  an  existing  Gmakefile  fiom  arwther  driver  and  modify  it  to  meet  die  needs  of  the 
new  digitizer  driver. 

Tte  following  libraries  are  needed  by  the  digitizer  driver  when  it  is  compiled: 

SGISBASEysnc/mapdev/digit/libdigita 

$GISBASE/src/niapdev/libes/libtians.a 

$GISBASEysrc/mapdev/lib/libdig.a 

$LIBDIR/iibdig_atts.a 


Some  iixrlude  files  (^.h)  must  also  be  compiled  into  the  driver.  Ihese  files  are  located 
in  the  following  directories: 

$GlSBASE/src/mapdev/libes 

$GISBASE/src/ma|xlev/lib 


Compile  the  device  driver  by  executiiig  Gmake.  This  will  create  the  digit  program  and 
any  other  programs  dependent  on  the  digitizer  driver  code. 


21.2.4  Testing  the  Device  Driver 

There  are  three  crucial  points  at  which  the  digit  program  calls  the  digitizer  driver.  The 
first  occurs  just  after  digit  has  prompted  the  user  for  a  file  name.  Digit  will  try  to 
open  the  driver  and  initialize  the  digitizer,  if  this  fails,  it  is  because 
P_setup_driverip.  197)  has  failed.  The  second  occurs  when  the  user  registers  the  m^ 
to  the  digitizer.  If  the  program  fails  at  this  point,  there  is  a  problem  with  the 

See  Corrpiluig  GRASS  Pivgrams  Using  Gmnke  l/>  S'?)  for  a  discussion  of  Gmake  and 
GmakefSes. 
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D_read.jaw(p.200)  function.  A  final  test  of  ti*  driver  is  perfoimed  when  the 
coUect_poirtts{p.  197)  function  is  called,  which  occurs  when  vectors  ate  being  digitized. 

Before  testing  any  progranns,  review  the  Grass  3.0  Installation  Guide  to  ensure  that 
the  digitizer  is  set  up  correctly.  If  mote  information  is  needed,  read  tire  file 
$GISBASEysrc/toapdev/README. 


21,3.  Disaission  of  the  Finar  Poiiils  (Hi^ 

This  section  offers  several  hints  and  pitfalls  to  avoid  when  writing  the  digitizer  driver. 
It  has  three  subsections:  Setting  up  the  Digitizer,  Regram  Logic,  and  ^recific  Driver 
Issues. 


21.3.1.  Setting  up  the  Digitizer 

The  process  of  setting  up  a  conputer  system  and  digitizer  can  be  divided  into  three 
steps: 

(1)  Setting  the  internal  switches  on  the  digitizer  (hardware) 

(2)  Running  a  cable  between  the  digitizer  and  the  conputer  (hardware) 

(3)  Settmg  up  tire  serial  port  on  the  conputer  (software) 


21.3.1.1.  Setdirg  the  internal  switches 

The  switches  on  the  digitizer  must  be  set  so  that  the  digitizer  will  run  under 
request  or  prompt  mode,  which  means  that  the  digitizer  will  only  send  output 
when  it  is  requested  or  pronpted  by  the  program  Thus,  the  program  controls  the 
timing  of  the  outpirt  from  the  digitizer  and  will  only  receive  information  when  it 
is  ready  to  process  it  Refer  to  the  manual  included  with  the  digitizer  for  specific 
information  on  its  set-up. 

Note.  The  digitizer  must  be  able  to  use  an  RS232  serial  interface  and  transmit 
information  only  when  pronpted  by  the  program  If  the  digitizer  can’ t  transmit 
information  on  command,  then  it  can’ t  be  used  as  a  GRASS  digitizer. 


21.3.1.2.  Running  a  cable  between  the  digitizer  and  conpurter 

A  cdble  must  be  made  to  connect  the  digitizer  to  a  RS232  serial  port  on  the 
conputer.  Different  model  conputers,  even  when  from  the  same  maker,  may 
require  different  cable  configurations.  For  example,  one  conputer  may  need  a 
straight-through  cable,  while  another  conputer  may  need  pins  6,  8,  and  20  looped 
back  on  the  conputer  side.  A  break-out  box  can  be  used  to  deduce  digitizer 
cable  requirements  and  ensure  tiiat  the  digitizer  is  actually  talking  to  the 
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coisputer. 


21.3.1.3.  Configuriiig  the  serial  port 

The  digitizer  is  plugged  into  a  serial  port  {/dev/tty?'?)  on  die  conoputer,  which 
must  be  configured  for  a  digitizer  to  run  on  it  To  set  iqi  the  tty  for  the  digitizer, 
turn  that  tty’ s  getty  off,  and  make  the  tty  readable  and  writable  by  anyone. 

A  final  suggestion:  document  the  information  that  has  been  learned.  The  file 
$GISBASEysrc/rrtipdev/digiti2ers/altek/]I^AIIjALTEK  can  be  used  as  an 
example.  It  contains  the  switch  settings  for  the  Altek,  cable  configurations,  and 
other  useful  information.  Such  documentation  is  invaluable  when  another 
digitizer  is  added,  problems  arise,  or  if  the  digitizer  switch  settings  have  to  be 
changed  because  other  software  is  using  the  digitizer. 


21.3.2.  I¥ogram  Logic 

All  digitizing  programs  follow  the  same  basic  steps,  whether  they  test  the  digitizer,  or 
appear  in  a  complex  digitizing  program  like  digit.  The  following  sequence  gives  the 
programmer  a  feel  for  how  tiie  digitizer  driver  is  used  by  the  calling  programs. 

( 1)  link  the  program  to  the  digitizer  (open  the  tty) 

(2)  Set  the  ity  to  the  ^propriate  state  (ioctt  calls) 

(3)  Initialize  the  digitizer  (setting  resolution,  setting  origin, ...) 

( 4)  Ask  the  digitizer  for  data  containing  a  set  of  coordinates 

(5)  Read  the  data  from  the  digitizer 

(6)  Interpret  the  data  into  usable  coordinates  (x,  y) 

(7)  Display  the  coordinates  (x,  y) 

(8)  Loop  back  for  more  data  or  until  usCT  wants  to  quit 

In  order  to  become  familiar  with  the  architecture  of  a  digitizer  driver,  it  is  useful  to 
write  a  ample  program  to  test  the  digitizer.  If  a  digitizing  problem  arises,  the 
diagnostic  program  can  help  isolate  the  cause  of  the  problem  (hardware,  software, 
cable,  etc.). 


21.3.3.  ^ledfic  Driva*  Issues 

The  writing  of  digitizer  device  drivers  can  be  complex.  This  section  explores  four 
issues  in  greater  depth 

( 1)  Clonnecting  to  tiie  digitizer 

(2)  Initializing  and  reading  the  digitizer 

(3)  Synchronizing  the  digitizer  and  computer 

( 4)  Digitizer  cursors  with  buttons 
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Connectiiig  to  the  digitizer: 

In  GRASS  3.0,  the  cornputer  communicates  diiectly  with  the  digitizer  to  vdnch 
(through  die  serial  port  tty)  the  digitizer  is  connected.  Tlie  tty  to  which  the 
digitizer  is  connected  is  opened,  read,  and  written  to  just  like  a  file. 

D_setup_tbiver{p.  197)  will  open  the  tty,  set  file  permissions  to  read  and  write, 
and  set  the  running  state  of  the  tty.  Some  aqperimenting  with  the  different  line 
disciplines  (CBREAK,  RAW)  may  be  necessaiy  to  deteimine  the  best  state  for 
the  tty,  but  RAW  seems  to  be  the  nomo.  Ghanging  the  running  state  of  a  tty 
consists  of  changing  the  structures  associated  widi  that  particular  tty  and 
reflecting  the  changes  to  the  operating  system  by  using  ioctli).  Unfortunately, 
die  information  is  stored  differendy  under  different  operating  systems. 

GRASS  digitizer  drivers  have  been  written  under  the  System  V  (AT&T)  and 
Beikeley  (UCB)  UNIX  operating  systems.  A  mqor  difference  between  these  two 
operating  systems  is  the  way  they  handle  teminal  interfaces  (ttys).  Terminal 
information  is  contained  in  structures  in  <teimio.k>  under  %stem  V,  and  in 
<sgtty.h>  under  Beikeley.  In  other  words,  the  structures,  and  die  names  used  in 
the  structures,  will  differ  dependiitg  on  the  operating  system.  AU  tty  related 
system-dependent  code  has  C  pre-processor  *if(kf  stahnents  around  it  in 

the  existing  drivers.  System-dependait  code  is  defined  as  either  beirig  under 
System  V  (SYSV)  or  Berkeley.  This  issue  will  only  arise  when  the  tiy  to  which 
the  digitizer  is  connected  is  being  opened,  uang  D_setup_dnver{p.  197). 

Initializirig  and  readirtg  the  digitizer: 

The  driver  and  the  digitizer  communicate  by  usiiig  the  UNIX  read( )  and  write  ( ) 
functions.  D_setupjJnver(p.  197)  sets  151  die  digitizer  software  by  writing 
command  striiigs  to  the  Shxe  each  digitizer  is  different,  the  digitizer’s  user 
manual  frequently  proves  to  be  the  only  source  of  information  on  how  to 
initialize  and  read  the  digitizer. 

Setting  up  a  consistently  good  function  to  read  the  digitizer  is  the  most  difficult 
part  of  writing  the  digitizer  driver.  The  readi )  function,  when  reading  from  a 
tty,  may  not  read  as  many  characters  as  requested.  For  example,  if  six  bytes  are 
requested,  read( )  can  return  anywhere  from  zero  to  six  bytes. 

(Dne  approach  is  to  request  six  bytes,  and  then,  if  the  number  of  bytes  actually 
read  isn’ t  six,  issue  another  read{ ),  tiiis  time  asking  only  for  the  number  of  bytes 
remaining.  In  other  words,  if  six  bytes  were  requested  but  only  two  were 
received,  then  another  read  for  four  bytes  is  issued  If  that  read  returned  one  byte, 
then  another  read  is  requested  for  three  bytes,  etc.  This  would  continue  until 
either  all  six  bytes  were  read,  or  a  time-out  occurred.  This  approach  worked  well 
in  the  Altek  driver. 


^  SYSV  is  defined  by  Grmke.  See  §7/  Conpiling  GRASS Progmms  Using  Grrnke  Ip  .‘>•51. 
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Anotiier  apinoach  that  was  tried  was  to  request  six  bytes,  and  dien,  if  less  than 
ax  bytes  woie  received,  the  bytes  were  thrown  away,  and  another  six  bytes  were 
requested.  This  was  repeated  until  the  read  returned  six  bytes.  Ihis  approach 
worised  some  of  the  time,  but  sometimes  gave  unreliable  coordinates,  and  was 
abandoned.  Otl^r  digitizer  drivers  have  been  written  that  read  ascii  characters 
from  the  digitizer  and  use  sscarfi )  to  strip  out  the  needed  infonnalion. 

The  number  of  characters  actually  read  to  get  one  set  of  coordinates  will  depend 
on  the  digitizer  and  on  the  information  stated  in  the  digitized  s  user  manual. 

Another  problem,  in  the  case  of  die  Altek,  is  that  the  cursor  is  only  active  in 
certain  portions  of  die  tablet  This  means  that  either  there  will  be  no  output  or  a 
specific  flag  will  be  on/off,  until  the  cursor  is  within  the  active  area  of  the  tablet 
Because  no  external  markings  on  the  tablet  delineate  the  active  area,  individuals 
commonly  attempt  to  digitize  within  the  tebletf  s  inactive  area,  leading  them  to  the 
false  assumption  that  the  digitizer  is  acting  strangely.  Depending  on  the  digitizer, 
this  will  Iwe  to  be  handled  by  flne-tuning  the  reads  and/or  checking  the  status 
byte(s). 

A  word  of  warning  -  if  die  tty  isn’t  set  up  properly  in D^tupjJriverip.  197),  the 
readi)  function  can  return  confusiiig  infonnalion  (i.e.,  it  may  include  garbage 
with  the  data  or  be  unable  to  read  die  number  of  characters  qi^ified). 

Syrrhronizing  the  digitizer  and  computer: 

Driver-checking  has  been  add^  to  posb-S.O  drivers,  to  warn  the  user  when  the 
driver  is  out  of  ?yrr  with  the  digitizer.  For  example,  the  Altek  has  the  hi^  bit 
turned  on  in  the  first  byte  of  the  ^  bytes  that  are  read.  The  driver  checks  to 
make  sure  that  the  high  byte  is  turned  on;  if  it  is  not,  the  digitizer  and  driver  are 
out  of  sync.  The  driver  warns  the  user,  resets  the  digitizer  gpid  then  re-initializes 
the  digitizer. 

Digitizer  cursors  with  buttons: 

Drivers  can  be  written  to  use  die  digitizer  buttons  or  the  keyboard  for  input  while 
digitizing.  Where  drivers  use  the  digitizer  buttons,  some  digitizers  will  queue  up 
any  button  hits.  (This  may  depend  on  what  running  state  the  digitizer  was  set  ip 
with  when  it  was  initialized.)  This  means  that  if  a  person  pushes  the  digitizer 
cursor  buttons  a  number  of  times  and  then  begins  to  digitize,  the  program  must 
clear  the  queue  of  button  hits  before  beginitiiig  to  digitize.  Other  digitizers  will 
only  say  that  a  button  has  been  hit  if  the  button  has  been  hit  and  the  digitizer  has 
been  prompted  for  a  coordinate. 
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Chapter  22 

Writing  a  Grapfaks  Driver 


22.1.  Introduction 

GRASS  3.0  application  programs  which  use  graphics  are  written  with  the  Easter 
Graphics  Library.  At  conpilation  time,  no  actual  graphics  device  driver  code  is 
loaded.  It  is  only  at  run-time  that  the  graphics  requests  make  their  way  to  device¬ 
specific  code.  At  run-time,  an  application  program  connects  with  a  running  graphics 
device  driver,  typically  via  system  level  firsfe-in-first-out  (fifo)  files.  Each  GRASS  site 
may  have  one  or  more  of  these  programs  to  choose  from.  They  are  managed  by  the 
programs  monitor,  DUst.mon,  Drelease.mon,  Dselect.mon,  Dstart.mon,  Dstatus.mon, 
Dstop.mon  and  DuMckmon. 

Porting  GRASS  graphics  programs  from  device  to  device  simply  requires  the  creation 
of  a  new  graphics  driver  program.  Once  completed  and  woridng,  aU  GRASS  graphics 
programs  will  worit  exactly  as  they  were  deagned  without  modification  (or 
reconpilation).  This  section  is  concerned  with  the  creation  of  a  new  graphics  driver. 


22.2.  Basics 

The  various  drivers  have  source  code  contained  under  the  directory 
$GISBASE/src/D/devices.^  This  directory  contains  a  separate  directory  for  each  driver, 
e.g.,  SUNVIEW  arxl  MASS.  In  addition,  (he  directory  lib  contains  files  of  code  which 
are  shared  by  the  drivers.  The  directory  GENERIC  contains  the  beginnings  of  the 
required  subroutines  and  sample  Gmnhefile. 

A  new  driver  must  provide  code  for  this  basic  set  of  routines.  Once  woridng,  the 
programmer  can  choose  to  rewrite  some  of  the  generic  code  to  increase  the 
perfomrance  of  the  new  driver.  Presented  first  below  are  the  required  routines. 
Suggested  options  for  driver  enhancement  are  then  described. 


'  $GISBASE  is  the  directory  wliere  GRASS  is  installed.  See  §10. J  UNIX  Errvironmerrt 
\r  .‘>/|  for  detail-s. 
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22.3.  Basic  Routines 

Described  here  are  the  basic  routines  required  for  constructing  a  new  GRASS  3.0 
graphics  driver.  These  routines  are  all  found  in  the  GEINERIC  directoiy.  It  is 
suggested  that  the  programmer  create  a  new  directoiy  (e.g.,  MYDRIVER)  into  ^iiich 
all  of  the  GENERIC  files  are  copied  (i.e.,  cp  GENERIC/*  MYDRIVER). 


22.3.1.  OpetyClose  Device 

Gra|)K.Set  ( )  initialvx  graphics 

This  routine  is  called  at  the  stEat-ito  of  a  driver.  Any  code  necessaiy  to  establish 
the  desired  graphics  environment  is  included  here.  Often  this  means  clearing  the 
gr^ducs  screen,  establishing  connection  with  a  mouse  or  pointer,  setting  drawing 
parameters,  and  establishing  the  dimensions  of  the  drawing  screen  In  addition, 
die  global  integer  variables  SCREENJLEFT,  SCREEN_RIGHr,  SCREEIN_TOP, 
SCREEN_EOTrOM,  and  NCOLORS  nuKt  be  set  Note  that  the  GRASS 
software  presumes  die  origin  to  be  in  the  iqiper  left-hand  comer  of  die  screen, 
meaning: 

SCREEISLLEFT  <  SCREENJUGHT 
SCREENLTOP  <  SCREEN_BCnTOM 

You  may  need  to  flip  the  coordinate  sy^m  in  your  device-specific  code  to 
sitoport  a  device  which  uses  the  lower  left  comer  as  die  origin  Ihese  values 
must  map  precisely  to  the  screen  rows  and  columna  For  eicample,  if  the  device 
provides  graphics  access  to  pixel  columns  2  through  1023,  then  these  values  are 
assigned  to  SCREENJjEFT  ansd  SCREERjUGHT,  reflectively. 

NCOLORS  is  set  to  the  total  number  of  colors  available  on  the  device.  This 
most  certainly  needs  to  be  more  than  100  (or  so). 

Grafih^Close  ( )  shut  doun  device 

Close  down  the  grEphics  processing.  This  gets  called  only  at  driver  termination 
time. 

22.3.2.  Return  Ec^  and  Color  Vdues 

The  four  raster  edge  values  set  in  the  Graph_Set( )  routine  above  are  retrieved  with  the 
following  routines. 
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ScreenJcft  (index) 

ScreeoJtite  (index) 

Screeo-top  (index) 

Screoubot  (index) 
int*index  ; 

The  requested  pixel  value  is  returned  in  index. 

These  next  two  routines  return  the  number  of  colors.  There  is  no  good  reason  for  both 
routines  to  exist;  chalk  it  up  to  the  power  of  anachroiisni 

Get-nuni-OGlors  (index)  return  nunber  of  colors 

int  *index  ; 

The  number  of  colors  is  returned  in  index. 

getJ11inL.oal.or8  (  )  return  nunber  of  colors 

The  number  of  colors  is  returned  directly. 


return  left  pixel  colurm  value 
return  right  pixel  colurm  value 
return  top  pixel  row  value 
return  bottom  pixel  row  value 


22.aa  Drawiiig  Routines 

The  lowest  level  drawing  routines  are  diawjinet ),  which  draws  a  line  between  two 
screen  coordinates,  and  R)lygon_abs( )  which  fills  a  polygon 

drawjtine  (xl,ylpc2,y2)  draw  a  line 

int  xl,  yl,  x2,  y2  ; 

This  routine  will  draw  a  line  in  the  current  color  from  xl^l  to  x2,y2. 

Bolygon^abs  ( x,y,n)  dvw  filled  polygon 

int  *x,  *y  ; 
int  n ; 

Using  the  n  screen  coordinate  pairs  represented  by  the  values  in  the  x  and  y 
arrays,  this  routine  draws  a  polygon  filled  with  the  currently  selected  color. 


22.3.4  Cdlors 

This  first  routine  identifies  whether  the  device  allows  the  run-time  setting  of  device 
color  look-iq)  tables.  If  it  can  (and  it  should),  the  next  two  routines  set  and  select 
colors. 
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Can_dD  ( )  signals  run-tinv  color  looh-up  table  access 

If  color  look-i^)  table  modiiicalion  is  allowed,  then  this  roijtine  must  return  1; 

.  otherwise  it  returns  0.  If  your  device  has  fixed  colors,  you  must  modify  the 
routines  in  the  /ib  directoiy  which  set  and  select  colors.  Most  devices  now  allow 
the  setting  of  the  color  look-iq)  table. 

reseLoolcr  (number,  red,  green,  blue)  set  a  color 

int  number ; 

unsigned  char  red,  green,  blue  ; 

The  system’s  color  represented  by  nuniier  is  set  using  the  color  conponent 
intensities  found  in  the  red,  green,  and  btue  variables.  A  value  of  0  represents 
0%  intensity;  a  value  of  255  represents  100%  intensity. 

ralor  ( number)  select  a  color 

int  number ; 

The  current  color  is  set  to  nuniier.  This  number  points  to  the  color  combination 
defined  in  the  last  call  to  reset  jpolori )  that  referenced  this  number. 


22.3.5.  Mouse  Input 

The  user  provides  input  through  the  three  following  routines. 

G€tJocatiaL.wHh-bax  (cx,cy,wx,wy, button)  get  location  with  rubber  box 

int  cx,  cy ; 
int  *wx,  *wy  ; 
int  *button ; 

Using  mouse  device,  get  a  new  screen  coordinate  and  button  number.  Button 
numbers  must  be  the  following  values  which  correspond  to  the  following  software 
meanings: 

1  -  left  button 

2  -  middle  button 

3  -  light  button 


A  ''ntober-band"  box  is  used.  One  comer  is  fixed  at  the  cx,cy  coordinate.  The 
opposite  coordinate  starts  out  at  wx,wy  and  then  tracks  the  mouse.  Upon  button 
depression,  the  current  coordinate  is  returned  in  wx,vry  and  the  button  pressed  is 
returned  in  button. 
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GeUocatkxu^iiithJine  (cx,cy,wx,wy,buttDn)  get  location  with  ntber  line 

int  cx,  cy ; 
int  *wx,  *wy ; 
int  ^button ; 

Using  mouse  device,  get  a  new  screen  coordinate  and  button  number.  Button 
numbers  must  be  the  following  values  which  correspond  to  the  following  software 
meanings: 

1  -  left  button 

2  -  middle  button 

3  -  right  button 

A  "rtbber-band"  line  is  used.  One  end  is  fixed  at  the  cx,cy  coordinate.  The 
opposite  coordinate  starts  out  at  wx,wy  and  then  tracks  the  mouse.  Upon  button 
depression,  the  current  coordinate  is  returned  in  and  the  button  pressed  is 

returned  in  button. 

GetJocatian_whlx_painter  ( wx,wy,button)  get  location  idth  pointer 

int  *wx,  *wy  ; 
int  *button ; 

Usirig  mouse  device,  get  a  new  screen  coordinate  and  button  number.  Button 
numbers  must  be  the  followirg  values  M^ch  correqwnd  to  the  following  software 
meanings: 

1  -  left  button 

2  -  middle  button 

3  -  tight  button 


A  cursor  is  used  which  starts  out  at  wx^wy  and  then  tracks  the  mouse.  Upon 
button  depression,  the  current  coordinate  is  returned  in  wx,wy  and  the  button 
pressed  is  returned  in  button. 


22.3.6.  Bandls 

The  following  routines  cooperate  to  save  arxl  restore  sections  of  the  display  screen. 
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PEndjBBve  (name,  top,  bottom,  left,  rig^  xax  a  panel 

char  *name ; 

int  top,  bottom,  left  right ; 

The  bit  display  betv^een  the  rows  and  cols  represented  by  tG|]^  bottom^  kft  and 
ri^  are  saved.  The  string  pointed  to  by  name  is  a  file  name  which  m£y  be 
used  to  save  the  image. 

PaneLrestere  (name)  restore  a  panel 

char  *name ; 

Race  a  panel  saved  in  name  (which  is  often  a  file)  back  on  the  screen  as  it  was 
when  it  was  saved.  The  memory  or  file  associated  with  name  is  removed. 


22.4.  Optional  Routbaes 

All  of  the  above  must  be  created  for  any  new  driver.  The  GRASS  Rasterlib,  which 
provides  the  ^plication  program  routines  which  are  passed  to  the  driver  via  the  fifo 
files,  contains  mary  more  grs^hics  options.  There  are  actually  about  44.  Above,  we 
have  described  19  routines,  some  of  which  do  not  have  a  counterpart  in  the  Rasterlib. 
For  GRASS  3.0,  the  basic  driver  library  was  expanded  to  accommodate  aU  of  the 
gr^hics  subroutines  which  could  be  accomplished  at  a  device-dependent  level  using 
die  19  routines  described  above.  This  makes  driver  writing  quite  easy  and 
straightforward.  A  price  that  is  paid  is  that  die  resultirig  driver  is  probably  slower  and 
less  efficient  than  it  might  be  if  more  of  the  routines  were  written  in  a  device- 
dependent  way.  This  section  presents  a  few  of  the  primary  target  routines  that  you 
would  most  likely  consider  rewritting  for  a  new  driver. 

It  is  suggested  that  the  driver  writer  copy  entire  files  from  the  lib  area  that  contain 
code  which  shall  be  replaced.  In  the  loading  of  libraries  during  the  compilation 
process,  the  entire  file  containing  an  as  yet  undefined  routine  will  be  loaded.  For 
exarrple,  say  a  file  "ab.c"  contains  subroutines  ai  )  and  b( ).  Even  if  the  programmer 
has  provided  subroutine  a( )  elsewhere,  at  load  time,  the  entire  file  "ob.c"  will  be 
loaded  to  get  subroutine  b( ).  The  compiler  will  likely  conplain  about  a  mulitply- 
defirted  external.  To  avoid  this  situation,  do  not  break  routines  out  of  their  files  for 
modification;  modify  the  entire  file. 
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Raslarjmt  (n,  nrows,  array,  witfazeios,  type)  raster  disfiiay 

intn ; 
int  nrows ; 
unsigned  int  *array ; 
int  withzeros ; 
int  type  ; 

This  is  the  basic  routine  for  lendeting  raster  im^es  on  the  screen.  Application 
programs  construct  images  row  by  row,  sending  the  corrpleted  rasters  to  the 
device  driver.  The  default  Raster  Jnt( j  in  lib  draws  the  raster  through  repetitive 
calls  to  colorO  and  drawJineO.  Often  a  20x  increase  in  renderir^  speed  is 
accorr^lished  through  low-level  raster  cedis.  The  raster  is  found  in  the  array 
pointer.  It  contains  color  information  for  n  colors  and  should  be  repeated  for 
nxMS  rows.  Each  successive  row  falls  under  the  previous  row.  (Dependirig  on 
the  complexify  of  the  raster  and  the  number  of  rows,  it  is  sometimes 
advantageous  to  render  the  raster  through  low-level  box  commands.)  The 
whhzeros  flag  indicates  whetiier  the  zero  values  i^uld  be  treated  as  color  0 
( withzeros=  =1)  or  as  invisible  (withzeros=  =0).  Finally,  fype  indicates  tiiat  the 
raster  values  ate  already  indexed  to  the  hardware  color  look-up  table  (fype=  =0), 
or  that  the  raster  values  are  indexed  to  GRASS  colors  (which  must  be  translated 
through  a  look-ip  table)  to  hardware  look-iq)  table  colors  (fype=  =1). 

Flirther  details  on  this  routine  and  related  routines  Raster _chr(),  and 
RasterjdefO  are,  of  course,  found  in  the  definitive  documentation:  the  source 
code. 
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Chapter  23 

Writing  a  Rdnt  Driver 


23.1.  Inbroductian 

The  pcdnt  system,  which  produces  hardcopy  maps  for  GR4SS,  is  able  to  stqpport  many 
different  types  of  color  printers.  This  is  achieved  by  placing  all  device-dependent  code 
in  a  separate  program  called  a  device  driver.  Application  programs,  written  usirig  a 
library  of  device-independent  routines,  communicate  with  the  device  driver  using  the 
UNIX  pipe  mechanism.  The  device  driver  translates  the  device-independent  requests 
into  graphics  for  the  device. 

A  paint  driver  has  two  parts:  a  shell  script  and  an  executable  program  The  executable 
program  is  responsible  for  trandating  device-independent  requests  into  graphics  on  the 
printer.  The  shell  script  is  responsible  for  setting  some  UNIX  environment  variables 
that  are  required  by  the  interface,  and  then  nmniiTg  the  executable  program 

The  user  first  selects  a  printer  usirig  the  Pselect  program  (or  the  related  paint  select 
option).  The  selected  printer  is  stored  in  the  GRASS  errvironment  variable 
PAINTER.^  Then  the  user  runs  one  of  the  application  programs.  The  principal  pain 
applications  that  produce  color  output  are  Pr^  (and  the  related  pain  nvp  option) 
which  generates  scaled  maps,  and  Pchart  (and  the  related  pain  chart  option)  which 
produces  a  chart  of  printer  colors.  The  application  looks  vp  fire  PAINTER  and  runs 
the  related  shell  script  as  a  child  process.  The  shell  script  sets  the  required 
environment  variables  and  runs  (he  executable.  The  application  (hen  comrauricates 
with  the  driver  via  pipes. 


'  See  ^10.2  GRA^EnLiroTVTent\p.52\. 
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23^  CreatiDg  a  SouiK»  Directory  fcr  the  1^^ 

The  source  code  for  paint  drivers  lives  in 
$GISBASEysrc/paiiit/Driveis^ 

Each  driver  has  its  own  sub-directoiy  containiiig  the  source  code  for  the  executable 
program,  the  shell  script,  and  a  Gmahsfile  with  rules  that  tell  the  GRASS  Gwahe 
command  how  to  compile  the  driver.^ 


2SJS.  The  Paint  Driver  Executable  Program 

A  paint  device  driver  program  consists  of  a  set  of  routines  (defined  below)  tiiat 
perform  the  device-dependent  functions.  These  routines  must  be  written  for  each 
device  to  be  sipported. 


23.3.1.  Pinter  I/O  Roudnes 

The  toUowiiTg  routines  open  the  printer  port  and  perform  low-level  i/o  to  the  printer. 

Popen  (port)  open  the  printer  port 

char  *port; 

Open  the  printer  port  for  output  If  the  port  is  a  tty,  perform  any  necessary  tty 
settings  (baud  rate,  xon/xoflf,  ete.)  required.  No  data  should  be  written  to  the 

port 

The  port  will  be  the  value  of  the  UNIX  environment  variable  MAPLP,'*  if  set 
and  NULL  otherwise.  It  is  recommended  that  device  drivers  use  the  port  that  is 
passed  to  them  so  that  paint  has  a  consistent  logic. 

The  baud  rate  should  rwt  be  hard-coded  into  PopeM ).  It  should  be  set  in  the 
driver  shell  as  the  UNIX  environment  varigJble  BAUD.  Popeni )  should 
determine  the  baud  rate  fro  n  this  environment  variable. 


SGISBASE  is  the  directoiy  where  GRASS  is  installed.  See  §i0.i  UNIX  Environment 
\p  5i\  for  details. 

See  §17  Compiling  GRASS  Prvgmms  Using  Gnake  lp.5.?I  for  details  on  the  GRASS 
compilation  process. 

'*  This,  and  other,  environment  variables  are  set  in  the  driver  shell  script  which  is  described 
in  §2.3.4  The  Deince  Driver  Siell  Script  \p.  222\. 
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Bout  (but',  n)  write  to  printer 

unsigned  char  *buf; 
intn; 

Ou4)ut  the  data  in  but  The  number  of  bytes  to  send  is  n.  This  is  a  low-level 
request  No  processing  of  the  data  is  to  be  done.  Output  is  simply  to  be  sent  as 
is  to  the  printer. 

It  is  not  required  that  data  passed  to  this  routine  go  immediately  to  the  printer. 
This  routine  can  buffer  the  output  if  deared. 

It  is  recommended  that  this  routine  be  used  to  send  all  output  to  the  printer. 

Poulc  (c)  unite  a  character  to  printer 

unsigned  char  c; 

Send  the  character  c  to  the  printer.  This  routine  can  be  implemented  as  follows: 

R)utE(c)  unsigned  chare; 

{ 

RduWc,  1); 

} 


Pouts  (s)  write  a  string  to  printer 

unsigned  char  *s; 

Send  the  character  string  s  to  the  printer.  This  routine  can  be  implemented  as 
follows: 

Fbuts(s)  unsigned  char  *s; 

{ 

RsuWs,  strien(s)); 

} 


Pflush  ( ) 

flush  arty  perxling  output  to  the  printer.  Do  not  close  the  port 


flush  pending  output 
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FdcseO 

Rush  ally  pending  ou^ut  to  the  printer  and  close  the  port 


close  the  printer  port 


Note.  The  above  routines  are  usually  not  device-dqiendent  In  most  cases  die  printer 
is  conr^ted  either  to  a  serial  tty  port  or  to  a  parallel  port  The  paint  driver  library® 
contains  versions  of  these  routines  which  can  be  used  for  output  to  either  serial  or 
parallel  ports.  Exceptions  to  this  are  tire  preview  driver,  which  sends  its  output  to  the 
graphics  monitor,  and  tiie  NULL  driver  which  s^ids  ddoug  output  to  stderr. 


23.3.2.  Initializaticn 

The  following  routine  will  be  called  sfter  PopenUp. 216)  to  initialize  the  printer: 

Pinit  ( )  initialize  the  printer 

Initialize  the  printer.  Send  whatever  codes  are  necessary  to  get  the  printer  ready 
for  printing. 


23.3.3.  Alpha-numeric  Mode 

The  following  two  routines  allow  the  printer  to  be  used  for  normal  text  printing: 

PalphaO  put  printer  in  text  mode 

Put  the  printer  in  alpha-numeric  mode.  In  this  mode,  the  driver  should  only 
honor  jRtexttp.  218)  calls. 

Ptext  ( text)  prirt  text 

char  *text; 

Rint  the  text  string  on  the  printer. 

The  t^  will  not  normally  have  noaprinting  characters  (i.e.,  control  codes,  tshs, 
linefeeds,  returns,  etc.)  in  it  Such  characters  in  the  tod;  should  be  ignored  or 
si^rpressed  if  they  do  occur.  If  the  printer  requires  ary  linefeeds  or  carriage 
returns,  this  routine  should  simply  them. 

Note.  If  the  printer  does  not  have  sipport  for  text  in  the  hardware,  it  must  be 
simiilated.  The  shinko635  printer  does  not  have  text,  and  the  code  from  that  driver  can 
be  used. 


See  §23.6  Paint  Diiner  Libimy  \p.  2241. 
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23.3.4  Graphics  Mode 

The  foUowii^g  routines  perform  raster  color  graphics: 

Praster  ( )  put  printer  in  graphics  nock 

Put  the  printer  in  raster  graphics  mode.  This  inplies  that  subsequent  requests  will 
be  related  to  generating  color  images  on  the  printer. 

I^ipixids  (nrows,  ncols)  report  printer  dirrensions 

int*nrows; 
int  *ncols; 

The  variable  ncnls  should  be  set  to  the  number  of  pixels  across  the  printer  page. 
If  the  driver  is  combining  pineal  pixels  into  larger  groipings  (e.g.,  2x2  pixels) 
to  create  more  colors,  then  needs  should  be  set  the  number  of  these  larger  pixels.® 

The  variable  nrows  should  be  set  to  0.  A  non-zero  value  means  that  the  output 
media  does  not  sipport  arbitrarily  lorig  output  and  paint  will  scale  the  output  to 
fit  into  a  window  nrows  x  nools.  The  ordy  driver  which  ^uld  set  this  to  a 
non-zero  value  is  the  preview  driver,  which  sends  its  output  to  the  graphics 
screen 

F^ctsize  (nrows,  ncols)  defined pictwe  siee 

int  nrows; 
int  ncols; 

Repare  the  printer  for  a  picture  with  nrows  arxl  ncxds.  The  number  of  columns 
nools  will  not  exceed  die  number  of  columns  returned  by  Pnpixels{p.2l9).^ 

There  is  no  limit  on  die  number  of  rows  i»ows  that  will  be  requested.  Paint 
assumes  that  the  printer  paper  is  essentially  infinite  in  length.  Some  printers  (e.g., 
thermal  printers  like  the  shinho635 )  only  allow  a  limited  number  of  rows,  after 
which  they  leave  a  gap  before  the  output  can  begin  again  It  is  up  to  the  driver  to 
handle  this.  The  output  will  siniply  have  gaps  in  it  The  user  will  cut  out  the 
gaps  and  tape  the  pieces  back  together. 


The  Prrvp  program  carnet  make  use  of  more  than  1024  pu®ls.  It  is  acceptable  for 
Pnpixels  (  )  to  set  ncols  larger  than  1024,  but  Pmap  will  reset  it  to  1024.  Wide  printers  will 
ix)t  (currently)  be  used  to  their  fullest  width.  When  Pmap  is  upgraded,  this  limitation  will 
disappear. 

^  The  programmer  should,  of  course,  code  defensively.  If  the  nuniDer  of  columns  is  too 
large,  the  driver  should  exit  with  an  error  message. 
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Pdata  (buf,  n)  send  raster  data  to  printer 

unsigned  char  *buf; 
intn; 

Output  the  raster  data  in  but  The  nuinber  of  bytes  to  send  is  n,  vdnch  will  be 
the  /jcofe  as  specified  in  the  previots  call  to  Ppictsize{p.2l9).  The  values  in  buf 
will  be  printer  color  numbers,  one  per  pixel. 

Note  that  the  color  numbers  in  buf  have  full  color  information  encoded  into  them 
(i.e.,  red,  green,  and  blue).  Some  printers  (e.g.,  inlget)  can  output  all  the  colors  on 
a  row  by  row  baas.  Others  (e.g.,  thermal)  must  lay  down  a  full  page  of  one 
color,  then  repeat  with  another  color,  etc.  Drivers  for  these  printers  will  have  to 
capture  the  raster  data  into  temporary  files  and  then  make  three  passes  through 
die  captured  data,  one  for  each  color. 

Rde  (buf,  n)  send  rle  raster  data  to  printer 

unsigned  char  *buf; 
intn; 

Output  the  run-lerigth  encoded  raster  data  in  but  The  data  is  in  pairs: 
color,  count,  where  color  is  the  raster  color  to  be  sent,  and  count  is  the  rnmber 
of  times  the  color  is  to  be  repeated  (with  a  count  of  0  meaning  256).  The 
number  of  pairs  is  n. 

Of  course,  all  the  counts  should  add  tp  to  ncols  as  specified  in  the  previous  call 
to  Ppictsize{p.219).  If  die  printer  can  handle  run-length  encoded  data,  then  the 
data  can  be  sent  either  direcdy  or  widi  minimal  manipulation.  Otherwise,  it  must 
be  converted  into  standard  raster  form  before  sending  it  to  the  printer. 


23.3.5.  Color  Information 

The  paint  ^stem  expects  that  the  printer  has  a  predefined  color  table.  No  attempt  is 
made  by  paint  to  download  a  specific  color  table.  Rather,  the  driver  is  queried  about 
its  available  colors.  The  following  routines  return  information  about  the  colors 
available  on  the  printer.  These  routines  may  be  called  even  if  Popenip:2l6)  has  not 
been  called. 
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PnooICKS  ( )  niarber  of  printer  colors 

lliis  routine  returns  the  number  of  colors  available.  Currently,  this  routine  must 
not  return  a  number  laiger  than  255.  If  the  piinter  is  able  to  generate  more  than 
255  colors,  the  driver  must  find  a  way  to  select  a  sibset  of  these  colors.  Also, 
the  paint  system  works  well  with  printers  that  have  around  125  different  colors. 
If  the  printer  only  has  three  colors  (e.g.,  cyan,  yellow,  and  magenta),  then  125 
colors  can  be  created  using  a  2x2  pixel.^ 

PDcdorlevds  (red,  green,  blue)  get  color  levels 

int  *red,  *green,  *blue; 

Returns  the  number  of  colors  levels.  This  means,  for  example,  if  the  piinter  has 
125  colors,  the  color  level  would  be  5  for  each  color,  if  the  printer  has  216 
colors,  the  color  levels  would  be  6  for  each  color,  etc. 

Pcxrlaniiim  (red,  green,  blue)  get  color  ramber 

float  red,  green,  blue; 

This  routine  returns  the  color  number  for  the  printer  which  most  closely 
approximates  the  color  specified  by  the  red,  green,  and  Uue  intenaties.  These 
intensities  will  be  in  the  range  0.0  to  1.0.^ 

The  printer  color  numbers  must  be  in  the  range  0  to  n-1,  where  n  is  the  number 
of  colors  returned  by  Pncolors{p.221). 

For  printers  tiiat  have  cyan,  yellow,  and  magenta  instead  of  red,  green  and  blue, 
tire  conversion  formulas  are: 

cyan  =  1.0  -  red 

yellow  =  1.0  -  blue 

magenta  =  1.0  -  green 


^  See  §23.S  Creating  125  Colors  From  3  Colors  \p.227\. 

^  Jjst  to  be  safe,  those  above  1.0  can  be  charged  to  1.0,  and  those  below  0.0  can  be 
changed  to  0.0. 
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Poolcrvatue  (n,  led,  green,  blue)  get  color  intensities 

intn; 

float  *red,  *green,  *blue; 

This  routine  confutes  tiie  red,  green,  and  Uue  intensities  for  the  printer  color 
nunober  n.  These  intensities  must  be  in  the  range  0.0  to  1.0.  n  is  not  a  valid 
color  number,  set  the  intenaties  to  1.0  (white). 


23.4.  The  Device  Driver  Shdl  Script 

The  driver  shell  is  a  snjaU  shell  script  which  sets  some  environment  variables,  and 
then  executes  the  driver.  The  following  variables  must  be  set:^® 

MAHJP 

This  variable  should  be  set  to  the  tty  port  that  the  printer  is  oa  The  tty  named  by 
tiiis  variable  is  passed  to  Popenip.2i6).  Only  in  very  special  cases  can  drivers 
justify  eitiier  ignoring  tihis  value  or  allowing  it  not  to  be  set 

The  driverc  distributed  by  USACERL  have  MAPIP  set  to  /dev/${PAINTER}. 
Thus  each  driver  must  have  a  corresponding  /dev  port  These  are  normally  created 
as  links  to  real  /dev/tfy  ports. 

BAUD 

This  specifies  the  baud  rate  of  the  ou4)ut  tty  port  This  variable  is  only  needed  if 
the  output  port  is  a  serial  RS-232  tty  port  The  value  of  the  variable  should  be  an 
integer  (e.g.,  1200,  9600,  etc.),  and  should  be  used  by  Popenip.216)  to  set  the 
baud  rate  of  the  fly  port 

HRES 

This  specifies  the  horizontal  r^lution  of  tiie  printer  in  pixels  per  inch  This  is  a 
positive  floating  point  number. 

VRES 

This  specifies  the  vertical  resolution  of  the  printa*  in  pixels  per  inch  This  is  a 
positive  floating  point  number. 

NCHARS 

This  specifies  the  maximum  number  of  characters  that  can  be  printed  on  one  line 
in  alpha-numeric  mode. 

Note.  The  application  programs  do  not  try  to  deduce  the  width  in  pixels  of  text 
characters. 

TEXTSCAUE 

This  positive  floating  point  number  is  used  by  Pimp  and  paint  map  to  set  the 
size  of  the  numbers  placed  on  the  grid  when  maps  are  drawn.  The  normal  value 

TTie  driver  shell  script  may  set  any  other  variables  that  the  progranmer  has  determined 
the  driver  needs. 
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is  1.0,  but  if  the  numbers  should  appear  too  large,  a  smaller  value  (0.75)  will 
shrink  these  numbers.  If  they  appear  too  small,  a  larger  value  (1.25)  will  enlarge 
them.  This  value  must  be  determined  by  trial  and  error. 

The  next  five  variables  are  used  to  control  the  color  boxes  drawn  in  the  map  l^end 
for  Prmp  and  paint  wap,  as  well  as  the  boxes  for  the  printer  color  chart  created  by 
Pchart  and  paint  chart.  They  have  to  be  determined  by  trial  and  error  in  order  to  get 
the  numbering  to  appear  under  the  correct  box.^^ 

NBLOCKS 

This  positive  integer  specifies  the  maximum  number  of  blocks  that  are  to  be 
drawn  per  line. 

BLOCKSIZE 

Tliis  positive  integer  ^)ecifies  the  number  of  pixels  across  the  top  of  an  individual 
box. 

BLOCKSPACE 

This  positive  integer  specifies  the  number  of  pixels  between  boxes. 

TEXTSPACE 

'nis  positive  int^er  specifies  die  number  of  space  characters  to  output  after  each 
number  (printed  under  the  boxes). 

TEXTFUDGE 

This  non-negative  int^er  provides  a  way  of  inserting  extra  pixels  between  every 
other  box,  or  every  third  box,  etc.  On  some  printers,  this  will  not  be  necessary,  in 
which  case  TEXTFUDGE  should  be  set  to  0.  If  you  find  that  the  numbers  under 
the  boxes  are  drifting  away  from  the  intended  box,  the  solution  may  be  to  move 
evay  other  box,  or  every  third  box  over  1  pixel.  For  example,  to  move  every 
other  box,  set  TEXTFUDGE  to  2. 

The  following  is  a  sample  paint  driver  shell  script: 


'  ’  Apologies  are  offered  for  this  admittedly  awkward  desiga 
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:  ${PAINrE]R?}  ${PAINr_DRIVEK?} 

MAHiP=/dev/$PAINEER 

BAUD=9600 

HRE5=85.8 

VRES=87.0 

NCHARS=132 

TEXTSCALE=1.0 

NB1jOCKS=25 

BLOCKSIZE=23 

BL0CKSPACE=13 

TEXTSPACE=1 

TEXTnJDGE=3 

export  MAFLP  BAUD  HRES  VRES  NCHARS 
export  TEXTSCALE  TEXTSPACE  TEXTFUDGE 
export  NBLOCKS  BLOCKSEE  BLOCKSPACE 

exec  SPAINTJDRIVER 


23.5.  Progranmmig 

The  paint  driver  uses  its  standard  input  and  standard  output  to  communicate  with  the 
paint  ^plication  program.  It  is  very  important  that  neither  the  driver  shell  nor  the 
driver  program  write  to  stdout  or  read  from  stdin. 

Diagnostics,  error  messages,  etc.,  should  be  written  to  stderr.  There  is  an  error  routine 
which  driver  programs  can  use  for  fatal  error  messages.  It  is  defined  as  follows: 

errar  (message,  perror) 

char  ^message; 
int  perror. 

This  routine  prints  the  message  on  stderr.  If  perro*  is  true  (i.e.,  norr-zero),  the 
UNIX  routine  perror  ( )  will  be  also  called  to  print  a  system  error  noessage. 
Finally,  eodti )  is  called  to  terminate  the  driver. 


23.6.  Paint  Driver  LitHrary 

The  paint  system  comes  with  some  code  that  has  already  be  written  This  code  is  in 
object  files  under  the  paint  driver  library  directory.  These  object  files  are: 


See  §23.7  Corrpiling  the  Driixr  (p  for  an  example  of  how  to  load  this  library  code. 
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mauLO 

IHs  fUe  contains  the  muni )  routine  idich  most  be  loaded  by  every  driver, 
since  it  contains  the  code  that  intetfaces  with  die  application  programs. 


io.o 

This  file  contains  versions  of  Popenip.216),  Poiit(p.217),  Poutcip.21'/), 
Pouts(p.2l7)y  Pfkiship.217),  and  Pclose(p.2I8)  which  can  be  used  with  printers  that 
are  connected  to  serial  or  parallel  ports.  These  routines  handle  the  tricky  tty 
interfaces  for  both  ^stem  V  and  B«feeley  UNIX,  allowing  full  8-bit  data  output 
to  tl£  printer,  with  xon/xofif  control  envied,  as  well  as  baud  rate  selection. 

colorsl25.o 

This  file  contains  versions  of  Pncolorsip.22l),  Pcolorlevels(p.22i), 
Pcolornurrip.221)^  and  Pcolorvalue(p.222)  for  the  125  color  logic  described  in 
§25.8  Creating  125  Colors  From  3  Colors  (p.227]. 


23.7.  Compffiiig  the  Driver 

Paint  drivers  are  compiled  using  the  GRASS  Gmake  utility  which  requires  a 
GmahefUe  contsaiing  coirpilation  rules.  The  following  is  a  san^le  Gmakefile : 


See  §7/  Corrpiling  GRASS  ProginmB  Using  Gntjke  \p.55\  for  details  on  the  GRASS 
compilation  pincess. 


§23  Writing  a  I\int  Drivo* 


-226- 


-226- 


NAME- 

sample 

DRTVERIJB  = 

$(S]^)/paut/Intaface/driveriib 

INTERFACE  = 

$(DK[VERLlB)/^nsiao  \ 

$(DRIVEBIJB)/io.o  \ 

$(DRIVERIIB)/colorBl25.o 

DRIVER_SHELL  = 

$(Erc)/paiiit/diiver.€h/$(NAMEJ 

DRIVER_E5CEC  = 

$(ErC)/paint/driver/$(NAME) 

OBJ  = 

alphao  texto  rastero  nf^l&o  \ 
pictaze.o  datao  rie.o 

1 

sill  $(DRIV litC—EKEXj)  $(T}RIVEH_SHEXjL)  j 

$(DRIVER^EXEC): 

$(OBJ)  $(LOCKLIB) 

cc  $(LDFLAGS)  $(1NTERFACE)  $(OBJ)  SiLOCKLIB)  -o  $@ 

SCDRIVER^SHELL) 

DRIVER.di 
tm  -f  $@ 
cp  $?  $@ 
chmod  +x  $@ 

$(OBJ); 

P.h 

$(LOCKLIB): 

There  are  some  features  about  this  Gmakefite  diat  should  be  noted: 
printer  name  (NAME) 

The  printer  name  sanple  is  assigned  to  the  NAME  variable,  which  is  then  used 
everywhere  else. 

paint  driver  library  (DRIVERLIB) 

This  driver  loads  code  from  the  common  point  driver  library.^'*  It  loads  rmin.o 
containing  the  rnaini )  routine  for  the  driver.  All  drivers  must  load  rrmn.o .  It 
loads  io.o  which  contains  versions  of  PoperAp.216),  Pout(p.217),  Poutcip.217), 
Pouts(p.2l7),  Pfluship.217),  and  Pcloseip.218)  for  serial  and  parallel  ports.  It  also 
loads  colorsl25.o  which  contains  versions  of  Pncolors(p.22l),  Pcolorlevelsip.221), 
Pcolomurrip.221),  and  Pcolorvalueip.222)  for  125  colors. 

lock  library  (LOCKLEB) 

The  driver  loads  the  lock  libaty.  This  is  a  GRASS  library  which  must  be  loaded 
if  the  Popenip.216)  from  the  driver  library  is  used. 

homes  for  driver  shell  and  executable 

The  driver  executable  is  compiled  into  the  driver  directory,  and  the  driver  shell  is 
copied  into  the  driversh  directory.  This  means  that  the  driver  executable  is 

.See  also  ^23.6 Paint  Driver  Ubiwy  lp.224]). 
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placed  in 

$GISBASE/etc/paint/driver^^ 
and  the  driver  shell  in 

$GISBASEyetc/painl/driver.sh. 


23.8.  C>eating  125  Colors  From  3  Ccdors 

The  paint  system  expects  that  die  printer  will  have  a  reasonably  large  nuirber  of 
colors.  Some  printers  support  a  large  color  table  in  the  hardware.  But  others  only 
support  three  primary  colors:  red,  green,  and  blue  (or  cyan,  yeUow,  and  magenta).  If 
the  printer  only  has  three  colors,  the  driver  must  simulate  more. 

If  the  printer  pixels  are  grouped  into  2r2  combinations  of  pixels,  then  125  colors  can 
be  sin^ated  For  exanple,  a  color  with  20%  red,  100%  green,  and  0%  blue  would 
have  one  of  the  four  pixels  painted  red,  all  four  pixels  painted  green,  and  none  of  the 
pixels  painted  blue. 

The  following  code  converts  color  intensify  in  the  range  0.0  to  1.0  into  a  number 
from  0-4  (i.e.,  the  numh.  - .  pixels  to  "turn  on"  for  that  color); 

if^ls  =  ( into:  s*  .  5  )  ; 
if  (ipixels  >  4) 
npixels  =-  4  ; 

This  logic  will  agree  with  the  125  color  logic  used  by  the  paint  driver  library^® 
rourdnes  Pncolors(p.221),  Pcolorlevelsip.221),  Pcolomurrip.221),  and  Pcolorvalueip.222), 
provided  that  the  color  numbers  are  assigned  as  follows: 

color_nuni)er  =  rpcLpixels  *  25  +  green_pixels  »  5'+  blue_pixels  ; 


SGISBASE  is  the  directory  where  GRASS  is  installed.  See  §J0.1  UNIX  Ehuirornnera 
I/).  .5/1  for  details. 

See  ^23.6  Paint  Driver  Librwy  \p.  2341. 
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Chapter  24 

WritiDg  GRASS  Shdl  Scripts 


This  section  describes  some  of  tiie  things  a  programmer  should  consider  when  writing 
a  shell  script  that  will  become  a  GRASS  command. 


24.1.  Use  the  Bourne  Shell 

The  Bourne  Siell  (/bin/sh)  is  the  original  UNIX  conanand  interpreter.  It  is  available 
on  most  (if  not  all)  versions  of  UNIX.  Other  command  interpreters,  such  as  tiie  C- 
Shell  (/bin/csh),  are  not  as  widely  available.  Therefore,  programmers  are  strongly 
encouraged  to  write  Bourne  Shell  scripts  for  maximum  portability. 

The  discussion  that  follows  is  for  the  Bourne  Shell  only.  It  is  also  assumed  that  the 
reader  knows  (or  can  leam)  how  to  write  Bourne  Shell  scripts.  This  chapter  is  intended 
to  provide  guidelines  for  making  them  work  property  as  GRASS  commands. 


24.2.  How  a  Script  Should  Start 

There  are  some  tilings  tiiat  should  be  done  at  the  beginning  of  any  GRASS  shell 
script: 

( 1)  Verify  that  the  user  is  running  GRASS,  and 

(2)  Cast  the  GRASS  environment  variables  into  the  UNIX  enviroment,^  and 
verify  that  the  variables  needed  by  the  shell  script  are  set 

The  following  accomplishes  these  two  things; 


’  See  §10  Ekuirorvnent  Variables  Ip.si] 
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if  test"$GISRC”  = "" 
then 

echo  "Sony,  you  are  not  running  GRASS"  >&2 
exit  1 
fi 

eval  'giaenv' 

:  ${GISBASE?}  ${GISDBASE?}  ${LOCATIQISLNAME?}  ${MASiPEJI?} 


Note  tte  use  of  the  :  command.  This  command  simply  evaluates  its  aiguments.  The 
first  use  is  as  the  first  character  of  the  file,  which  a^ials  to  UNIX  that  the  script  is  in 
fact  a  Bourne  9iell  script  (see  §24.5  Don’t  Use  *!MnMi  \p.231]).  The  second  use 
checks  to  see  that  variables  are  set  The  syntax  ${GISBASE?}  means  that  if  GISBASE 
is  not  set  issue  an  error  message  to  standard  error  and  edt  the  shell  script 


243.  Gask 

The  GRASS  corrrmand  Gask  emulates  the  prompting  found  in  all  other  GRASS 
commands,  and  should  be  used  in  shell  scripts  to  ask  the  user  for  files  from  the 
GRASS  database.  The  user^  s  re^nse  can  be  cast  into  shell  variables.  TTie  following 
example  asks  the  user  to  select  an  existir^g  ceU  file: 


Gask  old  "Select  a  cell  file"  cell  cell  /tnnp/$$ 
« /trnp/$$ 
rm  -f  /tmp/$$ 
if  test"$nanie"  = "" 
then 
exit  0 
fi 


The  Gask  manual  entry  in  the  GRASS  User’s  Reference  Manual  describes  this 
commarxi  in  detail.  Here,  the  reader  should  note  the  following: 

(1)  The  temporary  file  used  to  hold  the  user^s  response  is  ArrpS$-  'Hie 
Bourne  Shell  will  substitute  its  process  id  for  the  $$  thus  creating  a 
unique  file  name; 

(2)  The  next  line,  which  begins  with  a  dot,  sources  the  commands  contained 
in  the  terrporaty  file.  These  commands  are: 

name=somef/u/^ 

vcB^t=sonKthing 

^e=something 

Therefore,  the  variables  $name,  $m^set,  and  $file  will  contain  the  name, 
mapset  and  full  UNIX  file  name  of  the  cell  file  selected  by  the  user, 

( 3)  'Fhe  terrporary  file  is  removed;  and 

(4)  If  $name  is  empty,  this  means  that  the  user  changed  his  or  her  mind  and 
didn’ t  select  any  cell  file.^  In  this  case,  something  reasonable  is  done,  like 

The  other  variables  will  be  empty  as  well. 
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244.  Gfmdfile 

The  Gfindfile  commaaid  can  be  used  to  locate  GRASS  files  diat  were  q)ecified  as 
arguments  to  the  shell  script  (instead  of  prompted  for  with  Cask).  Assuming  that  the 
variable  $request  contains  the  name  of  a  ceil  file,  the  following  checks  to  see  if  the  file 
exists.  If  it  does,  the  variables  $name,  $mapset  and  $file  will  be  set  to  the  name, 
mapset  and  full  UNIX  file  name  for  the  cell  file: 


eval  Gfindfile  cell  "Srequest"' 
if  test  "$mapset"  =  "" 
then 

echo  EEIROR:  cell  file  "Srequest"  not  found  >&2 
exit  1 
fi 


Note.  The  programmer  should  use  quotes  with  $request,  since  it  may  contain  spaces. 
The  user  can  request  a  file  on  the  command  line  of  the  form  "name  in  mapset"^ 
(quotes  will  preserve  the  full  request).  GfMfile  accepts  this  form  and,  if  fourxi, 
outputs  $name  as  the  name  part  and  $mapset  as  the  mapset  part  See  the  Gfindfile 
manual  entry  in  the  GRASS  User’s  Reference  Manual  for  more  details. 


245.  Dcm’tUse#!/bin/idh 

When  a  user  runs  a  shell  script,  he  or  she  simply  types  the  name  of  ttie  shell  script  just 
as  if  it  were  a  compiled  program  On  ^sterns  that  have  more  than  one  shell,  it  is  the 
responsibility  of  UNIX  to  figure  out  which  shell  should  interpret  the  commands  in  the 
script  This  decision  must  be  made  on  the  basis  of  the  shell  for  which  the  script  was 
written 

On  systems  that  have  both  /bin/sh  and  /bin/csh,  the  rule  has  been  if  the  first  character 
of  the  file  is  then  the  script  is  given  to  /bin/csh  to  interpret;  otherwise,  it  is  given  to 
/bin/sh.  As  the  number  of  shells  available  grew,  the  mechanism  was  expanded  to 
allow  the  shell  script  to  explicitly  specify  the  interpreter.  The  rule  was  modified  so 
that  if  the  first  line  of  the  file  is: 

command  [args] 

then  the  command  ( with  the  specified  arguments)  is  invoked  as  the  script  interpreter. 

'I'his  led  to  /bin/sh  scripts  starting  with  #! /bin/sh.  However,  the  authors  have  found 
UNIX  systems  which  do  not  recognize  this  rule.  They  sinply  see  the  #  as  the  first 
cliaracter,  and  turn  the  script  over  to  /bin/csh  instead  of  /bin/sh.  Therefore,  scripts  for 

*  This  form  for  GRASS  file  names  is  discussed  under  ^12.52  Finding  Files  in  the  Database 

r  ■III 
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/bin^sh  shoidd  never  start  whfa  #.  A  to  start  Bourne  iSiell  script  that  has 
woifced  well  on  all  systems  with  which  the  authors  have  experience,  is  to  use  the  : 
command  (see  §24^  How  a  Script  Siovld  Start  (p.229]). 
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Appendix  A 

Annotated  Gmake  Redefined  Variables 


The  pre-defined  Gmake  variables  are  defined  in  the  files  mahehead  and  mahe.rrid 
These  files  can  be  foimd  imder  $GISBASE/src/CMD.^ 

Note.  Tte  variables  shown  here  are  described  in  more  detail  in  §22  ConpiUng  GBASS 
Programs  Using  Gmake  [p.55]. 


makehead 

The  makehead  file  contains  machine-dependent  and  installalion-dependent  infonnatioa 
It  is  created  by  system  personnel  when  GRASS  is  installed  on  a  system  prior  to 
compilation.  This  file  varies  finm  system  to  system. 


'  $G3SBASE  is  the  dinectoiy  where  GRASS  is  installed.  See  §20.i  UNIX  EhuirowTEnt 
I/J  .57I  for  details. 
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Armotated  san^ie  rnakehead  file 


Variable 

Value 

Description 

(3S 

=  /grass 

GRASS  installation  diiectoiy 

GaSDBASE 

=  /grass/data 

GRASS  datHhasR  diiectoiy 

UNDCBIN 

=  /uaylocal/bin 

UNDC  cornnand  bin  diiectoiy 

DEFAULTJjOCATION 

=  speariish 

Default  Lo'cation  for  new  useis 

OS 

=  SYSV 

Tty  interface  flag 

#OS 

=  BEBK 

OOMFTLELFIAGS 

=  -0 

Conpiler  options 

IDFIAGS 

=  -s 

Loader  options 

DIGrr_FLAGS 

= 

Digitizer  coinple  time  flag 

#DIGIT_FIAGS 

=  -DATr 

#DIGrr_FlAGS 

=  -DMASSCOMP 

MATHLBB 

=  -Im 

Mathlibraiy 

TERMLIB 

=  -Iteimlib 

Tenriib/termcap  libraiy 

CLEAR 

=  ok 

Can  use  teimlib  ta  clear  screen 

^CXjElAJi 

=  no 

AR 

=  ar  ruv  $@  $?;\ 

libiay  archive  rule  for 

ranlib  $@ 

Eystems  with  ranlib 

#AR 

=  arrc  $@\ 

libiay  archive  rule  for 

‘lorder  $(OBJ)  Itaoit 

systems  without  lanlib 
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make-inid 

The  mahe.rrid  file  uses  the  variables  in  mahehead  to  constnict  other  variables  that  are 
useful  for  conplation  rules.  The  contents  of  this  file  are  usually  unchanged  from 
system  to  system 


Annotated  rmhe.rrid  file 


Variable 

ValtB 

Description 

CFLAGS 

=  $(COMHLE_nAGS)  -I$(LIBDIR)\ 

-D$(OS)  $(EX'niA-CELAGS) 

Conpler  flags 

GMAKE 

=  $(GIS)/ac/CMD/GniakB 

Gnske  command 

MAKEALL 

=  set  -  *;  for  d  do\ 

test  -f  $$d/Gmakeme  &&  $(GMAKE)  $$d;\ 
done;  exit  0 

Gmake  "all" 

MANROFT 

=  fl)l  -TX  \ 

$(GIS)/srcAnan.help/maaheader  $?\ 

I  moflf  -Tip  1  col  -b  >  $@ 

rule  for  manual  pages 

CURSES 

=  -Icuraes  $(TERMLIB) 

Curses  libraries 

MANl 

=  $(GIS)/man/l 

Man  directoiy,  section  1 

MAN2 

=  $(GIS)Anan/2 

Man  directoiy,  section  2 

HELP 

=  $(GIS)/rinan/help 

Efelp  directoiy 

BIN 

=  $(GIS)/bin 

GRASS  command  directoiy 

ETC 

=  $(GIS)/ete 

GRASS  command  support  directoiy 

SRC 

=  $(GIS)/src 

GRASS  source  directoiy 

UBDIR 

=  $(GIS)/src/libes 

GRASS  libraiy  directoiy 

GISLIB 

=  $(LJBDIR)/libgis.a 

GIS  library 

IMAGERYLIB 

=  $(LiIBDIR)/libI.a 

Imagery  library 

LOCKUB 

=  $(IJBDIR)/liblock.a 

Lock  libraiy 

SEGMENTLIB 

=  $(LIBDIR)/libsegmenLa 

Segment  library 

DLGUB 

=  $(liBDIR)/1ibdlg.a 

Dig  library 

RASTERLIB 

=  $(SRC)/D/libea/rast0riib.a 

Raster  libraiy 

DISFLAYUB 

=  $<SRC)/D/libea^displaylib.a 

Di^ay  libraiy 

VASKUB 

=  $(1IBDIR)/Iibvask.a 

Vask  library 

VASK 

=  $( VASKUB)  $( CURSES) 

Vask  +  curses  libraiy 
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GRASS  cell  file  data  is  defined  to  be  of  type  CELL  'Hns  data  type  is  defined  in  the 
"gis.h"  header  file,  ftogrammere  must  declare  all  variables  and  buffers  which  wiU 
hold  cell  file  data  or  category  codes  (which  are  CELL  values  as  well)  as  type  CELL. 

Under  GRASS  3.0  the  CELL  data  type  is  declared  to  be  but  the  programmer 
should  not  assume  this.  What  should  be  assumed  is  that  CELL  is  a  signed  integer 
type.  It  may  be  chained  sometime  to  short  or  long.  This  implies  that  use  of  CELL 
d^  with  routines  which  do  not  know  about  this  data  type  (e.g.,  printft ),  sscanfT ),  etc.) 
must  use  an  intermediate  variable  of  type  long. 

To  print  a  CELL  value,  it  must  be  cast  to  long.  For  example: 

CEIJi  c;  /*  cell  value  to  be  painted  */ 

/*  some  code  to  get  a  value  for  c  */ 
printf  ("%ld\n",  (long)  c);  /*  cast  c  to  long  to  print  */ 


To  read  a  CELL  value,  for  example  from  user-typed  input,  it  is  necessany  to  read  into 
a  long  variable,  and  then  assign  it  to  the  CELL  variable.  For  example:^ 


char  useibufTl28]; 
CELLc; 
long  x; 


printf  ("Which  categoiy? "); 
gets(useibuf); 

gscanf  (userbuf,"%ld",  &x); 
c  =  (CELL)  x; 


/*  prompt  user  */ 

/*  get  user  re^nse  */ 

I*  scan  categoiy  into  long  variable  */ 
/*  assign  long  value  to  CELL  value  */ 


Of  course,  with  GRASS  library  routines  that  are  designed  to  handle  the  CELL  type, 
this  problem  does  not  arise.  It  is  only  when  CELL  data  must  be  used  in  routines 
which  don’t  know  about  the  CELL  type,  that  the  values  must  be  cast  to  or  from  long. 


'  This  exanple  does  not  check  for  valid  inpxits,  EOF,  etc.,  which  good  code  must  do. 
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liidex  to  GIS  library 


Here  is  an  index  of  GIS  library  routines,  with  calling  sequences  aixi  short  furrtion 
descriptions. 

GIS  Library 


routine 

descriotion 

page 

G_allocalB_celLbuf 

0 

allocate  a  cell  buffer 

86 

G_ask_any 

(prompt,  name,  element,  IdSel,  warn) 

prompt  for  anv  valid  file  name 

70 

G_a^celLin_nnapeet 

(pron^  name) 

prompt  for  existing  cell  file 

81 

G_ask_celLnew 

(prompt,  name) 

prompt  for  new  cell  file 

81 

G_asleceiLold 

(prompt,  name) 

prompt  for  existing  cell  file 

81 

G_ask_in_rnapeet 

(prompt,  name,  element,  label) 

ITOrrq>t  for  existing  database  file 

70 

G_ask_new 

(prompt,  name,  element,  Istoel) 

prompt  for  new  dstabaee  file 

69 

G_ask_old 

(prompt,  name,  element,  label) 

prompt  for  existing  riatsthaae  file 

69 

G_ask_sites_in_mapeet 

(prompt,  name) 

fMompt  for  existing  site  list  file 

106 

G_ask^sites_new 

(prompt,  name) 

prompt  for  new  site  list  file 

106 

G_aslesities_old 

(prompt,  name) 

prompt  for  existing  site  list  file 

106 

G_ask_vectDr_in_m£|3set 

(prompt,  name) 

pron^  for  an  existing  vector  file 

101 

G_ask_vectDr_new 

(prompt,  name) 

prompt  for  a  new  vector  file 

101 

G_asle  vec  tor_old 

(pronpt,  name) 

prorr^  for  an  existing  vector  file 

101 

G_calloc 

(n,  size) 

memory  allocation 

76 

G_close_cell 

(fd) 

close  a  cell  file 

89 

G_dalE 

0 

current  date  and  time 

117 

Gj'atal_error 

(mesBage) 

print  error  message  and  exit 

64 

GjincLcell2 

(name,  m^fieet) 

find  a  cell  file 

82 

G_fincLcell 

(nattte,  metpset) 

firxl  a  cell  file 

82 

G_find_file2 

(element,  name,  mapeet) 

find  a  database  file 

71 

G_find_fiJe 

(element,  name,  mapset) 

find  a  database  file 

71 

G_firxLvectoi2 

(name,  mapset) 

find  a  vector  file 

102 

G_lind_  vector 

(name,  mapeet) 

fiixl  a  vector  file 

102 

G_fopen_append 

(element,  rume) 

open  a  database  file  for  update 

73 

G_lopen_ncw 

(element,  name) 

open  a  new  database  file 

74 

G_ropen_()ld 

(element,  name,  mapeet) 

open  a  database  file  for  reading 

73 

G_tbpenL_si  tes_new 

(name) 

open  a  new  site  list  file 

107 

G_toperLa  tes_old 

(name,  mapset) 

open  an  existing  ate  list  file 

107 

G_ropt'n_\’ec  tor^now 

(name) 

open  a  new  vector  file 

104 

G_ro|.x'n_  \(x:t()r_()ld 

(name,  mapset) 

open  an  existing  vector  file 

103 

( ) 

create  a  protected  child  process 

116 

(cats) 

free  category  structure  memory 

94 

(Llii'i’  colofs 

(colors) 

free  coloi  structure  memorv 

96 

G_(rc-Lasl^ieUirr\.  rasj' 

( ) 

get  Hit  RFTTURN  msg 

70 

G_geLcal 

(n,  cats) 

get  a  category  label 

93 

G_t<eLcaLs_titJe 

(cats) 

get  title  from  categorv  structure 

93 

GjjeLcellhd 

(name,  mapset,  cellhd) 

read  the  cell  header 

90 

G_gt'Lce!l_titJe 

(name,  mapeet) 

get  cell  tide 

92 

G„get_tol()r 

(cat,  It'd,  gieen,  blue,  colois) 

get  a  category  color 

95 

• iret,  rIeCaul  L  w  j  ndo  w 

(window) 

read  the  default  wirxiow 

78 
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GIS  Libiaiy 


routine 

narametera 

description 

oafis 

G__getEnv 

(name) 

query  GRASS  ertvironment  variable 

67 

G_getenv 

(name) 

query  GRASS  environment  variable 

67 

G_get_map_row 

(fd,  cell,  row) 

read  a  cdl  file 

87 

G_get.iT»ap_row_nomask 

(fd,  cell,  row) 

read  a  cell  file  (without  maddng) 

87 

G_getB 

(buf) 

get  a  line  of  input  (detect  ctrl-z) 

117 

G_get;_9eLwi  ndo  w 

(window) 

get  the  active  window 

79 

G_get_sitE 

(fd,  east,  north,  desc) 

read  site  list  file 

107 

G^et.window 

(window) 

read  the  database  wirdow 

77 

G_gisbase 

0 

top  level  program  directory 

66 

G_gigdbase 

0 

top  level  database  directory 

67 

G_gisinjt 

(program_name) 

initialize  gis  librarv 

64 

G_home 

0 

user' s  home  directory 

117 

G_init.cats 

(n,  tide,  cats) 

initialize  category  structure 

93 

G_init_colore 

(colors) 

initialize  color  structure 

96 

G_init_range 

(range) 

initialize  range  structure 

100 

G_intr_char 

0 

return  interrupt  char 

117 

G_is_  reclass 

(name,  mapset,  r_name,  r_mapeet) 

reclass  file? 

91 

G_legaLfilename 

(name) 

check  for  legal  database  file  names 

72 

GJocation 

0 

current  location  name 

66 

G_location_path 

0 

current  location  diiectorv 

67 

G_niake_aspec  Lcolore 

(colors,  min,  max) 

make  aspect  colors 

97 

G_tTiake_color_ramp 

(co'ors,  min,  max) 

make  color  ramp 

97 

G_m^_color_wave 

(colors,  min,  max) 

make  color  wave 

97 

G_tTiake_grey_scale 

(colors,  min,  max) 

make  linear  grey  scale 

97 

G_make_rainbow_colois 

(colors,  min,  max) 

make  rainbow  colors 

97 

G_make_random_colors 

(colors,  min,  max) 

make  random  colors 

98 

G_make_recLyel_gm 

(colors,  min,  max) 

make  red,yel]ow,gTeen  colors 

98 

Gjnalloc 

(size) 

memory  allocation 

76 

G_mapeet 

0 

current  mapset  name 

66 

G_myname 

0 

location  tide 

66 

G_opert_celLnew 

(name) 

open  a  new  cell  file  (sequential) 

84 

(j_open_celLnew_random 

(name) 

open  a  new  cell  file  (random) 

85 

G_opea.cell_new_ uncompressed  (name) 

open  a  new  cell  file  (uncompressed) 

85 

G_open_celLoid 

(name,  mapset)  { 

!  open  an  existing  cell  file 

8.3 

<  ;_open_ncw 

(element,  name) 

open  a  new  database  file 

74 

G_open_old 

(element,  name,  m^jset) 

open  a  database  file  for  reading 

72 

G_open_update 

(element,  name) 

open  a  database  file  for  update 

73 

( ]_par9e_comniand 

(aigc,  argv,  keys,  stash) 

parse  commarKi  line 

109 

( ;  parsc_command_ usage 

(program,  keys,  format) 

command  litre  usage  message 

111 

( Lpcicent 

(n,  total,  itKr) 

pint  percent  comj^ete  messages 

117 

^  •  pn)giTiin_name 

0 

return  program  name 

118 

(;  pn)je<  li()n_n;ime 

(proj) 

query  cartographic  projection 

80 

(.  puyecUon 

0 

query  cartographic  projection 

80 

( .  puLcellhd 

(niune,  cellhd) 

write  the  cell  header 

90 

(i'_puLcell_tjtJe 

(name,  title) 

change  cell  title 

92 

^  ’>_puLmap_r[)w 

(I'd,  buf) 

wmte  a  cell  file  (sequential) 

88 

1  '>_pul_map_row_inndom 

(fd,  buf,  row,  col,  rrcells) 

write  a  cell  file  (random)  - 

88 

O  put  site 

(fd,  east,  north,  desc) 

write  ate  list  file 

108 

G_puLwind«w 

(window) 

rvrite  the  database  wirxiow 

77 

( iv;ri_cats 

(name,  nrapeet,  cats) 

read  cell  catcgoiv  file 

91 

<  1  tv;\d_colois 

(name,  mapset,  colors) 

read  map  laver  color  Ubie 

94 
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niuUtw  _  _ _ _ 

.G_reafLhistoty 

GjneatLrange 

G_reacLvectDr_cals 

G_realloc 

G_ren»ve 

G_renan)e 

G_row_update_raige 

G_set_aBk_netum_m^ 

G_set_cat 
G_set_cat3_dtie 
G_set_color 
G_  _9etEnv 
G_setenv 

G_9eL.enDr_routine 
G_selL  window 
G_shorLhistDry 
G_sleep_on_em)r 
G_9queeze 

G_stDre 

G_strcat 

G_strcpy 

G_sirip 

G_stmcpy 

G_suppress_  wami  ngs 

G_system 

G_tiempfiJe 

G_tBlcaBe 

G_tDucaae 

G_unctil 
G_unoperL.cen 
G_unset_ent)r_nDutine 
G_update_range 
G_  warning 

G_whoami 

G_window_cols 

G_window_rows 

G_write_cats 

(J_writ<'_colors 

<i_wTite_histDry 

G_wTite_range 

G_wTite_vector_cats 

G_yes 

G_zciT>_ct'll_buf 

G_zone 


GIS  Libraiy 


punmnelcm 

dcscriniion 

Dasc 

(name,  m^set,  histoiy) 

read  cell  histoiy  file 

98 

(name,  nuiset,  range) 

read  cell  range 

99 

(name,  mapeet,  cabs) 

read  vector  category  file 

106 

(jXr,  size) 

memoiy  allocation 

76 

(element,  nane) 

remove  a  Hatahasp  file 

75 

(element,  old,  new) 

rename  a  database  file 

76 

(cell,  n,  range) 

update  range  structure 

100 

(msg) 

set  Ifit  RETURN  m^ 

70 

(n,  label,  cats) 

set  a  categoiy  labd 

94 

(title,  cats) 

set  title  in  categoiy  structure 

94 

(cat,  red,  green,  blue,  colors) 

set  a  category  color 

96 

(name,  vadue) 

set  GRASS  emiionment  vaii^e 

67 

(name,  value) 

set  GRASS  environment  variable 

67 

(handler) 

change  error  handling 

66 

(window) 

set  the  active  window 

79 

(name,  fype,  histoiy) 

initialize  histoiy  structure 

99 

(flag) 

sleq)  on  erroi? 

66 

(s) 

remove  linnecessaiy  white  qaace 

113 

(s) 

copy  string  to  allocated  memory 

114 

(dst,  SIC) 

concatentate  strings 

113 

(dst,  sic) 

copy  strings 

113 

(s) 

remove  leading/training  white  space 

114 

(dst,  SIC,  n) 

copy  strings 

113 

(flag) 

suppress  warning^ 

66 

(command) 

run  a  shell  level  command 

116 

0 

returns  a  ten^raiy  file  name 

108 

(s) 

convert  string  to  lower  case 

114 

(s) 

convert  string  to  i^^rer  case 

114 

(0 

printable  veraon  of  control  characte- 

114 

(fd) 

unopen  a  cell  file 

89 

() 

reset  normal  error  handling 

66 

(cat,  range) 

update  range  structure 

100 

(message) 

print  warning  message  and  continue 

64 

0 

user's  name 

118 

0 

number  of  columns  in  active  window 

78 

0 

number  of  rows  in  active  window 

78 

(nane,  cats) 

write  cell  categoiy  file 

92 

(name,  mtpset,  colois) 

write  map  layer  color  table 

95 

(name,  histoiy) 

write  cell  history  file 

99 

(name,  range) 

write  cell  range 

100 

(name,  cats) 

write  vector  category  file 

105 

(question,  default) 

ask  a  ves/no  question 

118 

(buf) 

zero  a  cell  buffer 

86 

() 

query  cartographic  zone 

80 

Index  to  GIS  Library 


Appendix  D 
Index  to  Dig  UlNrary 


Here  is  an  index  of  Dig  libraty  routines,  widi  callirg  sequences  and  short  function 
descriptions. 


Dig  Libraiy 


routine 

oaianieteis 

descriiXion 

dig_bound_box 

(p.  N,  S,  E,  W)  i 

get  arc  bounding  box 

135 

dig_chiect.dist 

(map,  n,  X,  y,  d) 

distance  to  are 

132 

dig_distance2_poi  nt_tD Jine 

(x,  y,  xl,  yl,  x2,  y2) 

distance  to  line-segment 

134 

clig_fini 

(fd) 

end  level  one  vector  access 

125 

clig_init_box 

(N.  S,  E,  W) 

limit  are  seareh  in  box 

127 

dig_irut 

(fd) 

initialize  level  one  vector  access 

125 

dig_P_area_att 

(m£p,  n) 

get  area  categoiy  attribute 

130 

dig_P_fini 

(ni£p) 

end  level  two  vector  access 

128 

dig_P_get_area_bbox 

(map,  n,  N,  S,  E,  W) 

get  area  bounding  box 

130 

dig_P_get_aea 

(map,  n,  pa) 

get  area  polygon 

129 

di&.P_get_area_xy 

(map,  n,  np,  x,  y) 

get  area  pol>^n 

129 

clig_P_getJine_bbox 

(m^,  n,  N,  S,  E,  W) 

get  arc  bounding  box 

131 

dig_P_init 

(name,  mapaet,  map) 

initialize  level  two  vector  access 

128 

dig_P_line_att 

(msp,  n) 

get  arc  category  attribute 

131 

di&.P_num_aneas 

(map) 

get  number  of  areas 

129 

clig_P_num_lines 

(map) 

get  nuntoer  of  arcs 

130 

dig_poinLia_aiea 

(map,  X,  y,  pa) 

point  in  area 

132 

dig_poinLtD_aiea 

(map,  X.  y) 

find  area  with  point 

132 

(iig_  point.  tD_line 

(map,  X,  y,  type) 

find  arc  with  point 

132 

dig^P_n(?acLlino 

(map,  n,  p) 

read  arc 

130 

dig.l  LreacLnext,!  ine 

(map,  p) 

•  read  next  arc 

131 

dig_P_trwind 

(map) 

rewind  nextrarc  pointer  . 

131 

dig.  ptinLheadir 

() 

displ^  vector  header  information 

125 

diK„pmne 

(p,  threshold) 

prune  a  dense  arc 

135 

dig_P_tnip_cl()sc 

(map) 

temporary  close  vector  map 

1-28 

dig  r^tinp.op'n 

(map) 

reopen  closed  vector  map 

128 

dig_  n-ixLheacL  biniuv 

(fd,  header) 

read  vector  header 

134 

dig.Kc'acLIirx' 

( fd,  offset  X.  y.  np) 

read  arc 

1.33 

dig_ii'.)d  lino.  in_b()x 

(fd,  np,  X,  y) 

read  arc  in  box 

127 

dig_ n'ail„ix'xi  lirx' 

(fd,  np,  X,  y) 

get  next  arc 

126 

dig  ivad.ix'xi  liix-.  ivfX' 

1  fd,  np,  X,  y,  type) 

get  next  arc  by  type 

126 

dig  u'uiiid 

(fd) 

lewirKl  vector  tile 

125 

dig  \Mll('.  llt'iKl  IllllillX 

1  Id,  healiT) 

write  vector  header 

1.34 

dig  VV  nil'  line 

(fd,  type.  X,  y,  np) 

write  are 

1.^3 

dig  di.--i.ini  r;-!  |i<iint,.li) .Inie 

(x,y,xl,yl,x2,\’‘2) 

distance  to  line-segment 

135 
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Here  is  an  index  of  Dig  Imagety  routines,  with  calling  sequences  and  short  function 
descriptions. 


Dig  Imggeiy 


routine 

DaramelEts 

descriotion 

dig_bound_box 

(p,  N,  S,  E,  W) 

get  arc  bounding  box 

136 

dig_check_dist 

(map,  n,  X,  y.  d) 

distance  to  arc 

132 

dig_distance2_poi  nl<_to  J  ine 

(x,  y,  xl,  yl,  x2,  y2) 

distance  to  line-segment 

134 

dig_fini 

(fd) 

end  level  one  vector  access 

125 

dig_init.box 

(N.  S,  E,  W) 

limit  arc  search  in  box 

127 

dig.init 

(fd) 

initialize  level  one  vector  access 

125 

dig_P_area_att 

(map,  n) 

get  area  cdegoiy  attribute 

130 

dig_P_fini 

(map) 

end  level  two  vector  access 

128 

dig_P_get_area_bbox 

(map,  n,  N,  S,  E,  W) 

get  area  bounding  box 

130 

dig_P_get_area 

(map,  ti,  pa) 

get  area  polygon 

129 

ciig_P_get.aneajy 

(map,  n,  np,  x,  y) 

get  area  polygon 

129 

dig_P_getJine_bbox 

(map,  n,  N,  S,  E,  W) 

get  an:  bounding  box 

131 

dig_P_init 

(name,  mapeet,  map) 

initialize  level  two  vector  access 

128 

dig_P_Une_att 

(map,  n) 

get  arc  category  attribute 

131 

dig_P_num_arEas 

(map) 

get  number  of  areas 

129 

dig.P_num_lines 

(map) 

get  nunirer  of  arcs 

130 

ciig_poinLiruarea 

(map,  X,  y,  pa) 

point  in  area 

132 

dig_poinLto_area 

(map,  X,  y) 

find  aea  with  point 

132 

dig_pointLto_line 

(map,  X,  y,  type) 

find  arc  with  point 

132 

dig_P_nead_line 

(map,  n,  p) 

read  arc 

130 

dig_P_reacLnextJ  ine 

(map,  p) 

read  next  arc 

131 

dig_P_rewind 

(map) 

rewind  next-arc  pointer 

131 

dig_print_header 

0 

di^^  vector  header  information 

125 

dig_  prune 

(p,  threshold) 

prune  adense  arc 

ia5 

dig_P_tmp_close 

(map) 

temporaiy  close  vector  map 

128 

dig_P_trnp_open 

(map)  ^ 

reopen  closed  vector  map 

1-28 

dig_read_heacL  binary 

(fd,  header) 

read  vector  header 

134 

dig_Read_line 

(fd,  offset,  X,  y,  np) 

read  arc 

133 

dig_read_line_irubox 

(fd,  np,  X,  y) 

read  arc  in  box 

127 

dig_read_next_line 

(fd,  np,  X,  y) 

get  next  arc 

126 

dig_  tvad_rK‘x  L  li  ne_typi' 

(fd,  np,  X,  V,  type) 

get  next  arc  by  type 

126 

dig_rewirKi 

(fd) 

rewind  vector  file 

VIF, 

dig_wTitc_hc'aci_bi  niiry 

(fd,  header) 

write  vector  header 

i:i4 

dig_WntpJine 

(fd,  type,  X,  y,  np) 

write  arc 

133 

dig_xy_disUince2_potni.tD_line 

(x,y,xl,yl,x2,v'2) 

distance  to  line-segment 

1.'?.6 

Index  to  Imagery  library 
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Here  is  an  index  of  Display  Gi:aphics  Library  routines,  with  callrag  sequences  and 
short  function  descriptions. 


Display  Graphics  Libraiy 


routine 

narameleis 

descriotion 

paRe 

D_adcLtDjist 

(string) 

add  command  to  mndow  di^l^  list 

161 

D_a_to_cLcol 

(column) 

array  to  screen  (column) 

163 

D_a_tD_d_row 

(row) 

aray  to  screen  (row) 

163 

D_cell_draw_setup 

(top,  bottom,  left,  righO 

prepare  for  raster  grafiiics 

165 

D_c  hec  k_rn^_  wi  ndo  w 

(window) 

asagn/retrieve  current  map  window 

160 

D_c  lear_  window 

0 

clear  wirxlow  display  lists 

161 

D_clear_  window 

0 

clears  information  about  current  window 

161 

D_clip 

(s,  n,  w,  e,  X,  y,  c_x,  c^) 

clip  coordinates  to  window 

166 

D_do_converaQns 

(window,  top,  bottom,  left,  right) 

initialize  converaons 

162 

D_draw_cdLrow 

(row,  raster) 

render  a  raster  row 

165 

D_cLtD_a_col 

(x) 

screen  to  array  (x) 

164 

D_d_iD_a_row 

(y) 

screen  to  aray  (y) 

164 

D_d_tD_u_col 

(x) 

screen  to  earth  (x) 

164 

D_d_tD_u_row 

(y) 

screen  to  earth  (y) 

164 

D.enase.  window 

0 

erase  current  window 

161 

D_get_celLname 

(name)  , 

retrieve  cell  file  name 

162 

D_geLcur_wind 

(name) 

identify  current  giephics  window 

160 

D_get_acn3en^window 

(top,  bottom,  left,  right) 

retrieve  current  window  coordinates 

160 

D_new_  window 

(name,  top,  bottom  left,  right) 

create  new  grapMcs  window 

160 

D_overiay_ceU_row 

(row,  raster) 

render  a  raster  row  without  zeros 

166 

D_popup 

(hcolor,  tcolor,  dcolor,  top,  left,  size,  options) 

pop-up  menu 

166 

D_rernove_  wi  ndow 

0 

remove  a  window 

161 

D_reset_colore 

(colors) 

set  colors  in  driver 

167 

D_reset_sc  reen_  wi  ndo  w 

(top,  bottom  left,  right) 

resets  current  wirxlow  position 

161 

D_seLcel  Lname 

(name) 

add  cell  file  name  to  display’  list 

162 

D_seLcu!'_wind 

(name) 

set  current  graphics  window 

160 

D_show_window 

(color) 

outlines  current  window 

160 

D_tiitiestanip 

0 

give  current  time  to  window 

161 

D_transl  ate_c  olor 

(name) 

color  name  to  number 

167 

D_u_tD_a_col 

(east) 

earth  to  array  (cast) 

163 

D_u_ti)_a_row 

(north) 

earth  to  array  (north) 

163 

1  )_u_to_d_col 

(east) 

earth  to  screen  (east) 

164 

1  )_u_(o^d_row 

(noith) 

earth  to  screen  (north) 

163 

Index  to  Display  Graplucs  IJbrary 
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Inds  to  Raster  Graphics  Library 


Here  is  an  index  of  Raster  Graplics  library  routines,  widr  calling  sequences  and  short 
function  descriptions. 


Raster  Grai^cs  Libraiy 


loutine 

oarameteis 

descriotion 

paRe 

R_box_abs 

(xl,ylpc2,y2) 

fill  a  box 

151 

R_box_rel 

(dx,dy) 

fiU  a  box 

151 

R_close_driver 

0 

temninate  gr^hics 

148 

R_color 

(color) 

select  color 

149 

tv.color_table_fixed 

0 

select  fixed  color  tablo 

149 

R^color_table_float 

0 

select  floating  color  table 

149 

R^cont_abs 

(x.y) 

draw  line 

151 

FLcont_rel 

(dx,dy) 

draw  line 

151 

FLerase 

0 

erase  screen 

152 

R_flush 

0 

flush  graphics 

152 

lijbnt 

(font) 

choose  font 

155 

R_get_location_with_box 

(x,y,nx,ny, button) 

g^t  mouse  location  uang  a  box 

157 

R_get_loc  atio  n_wi  th_li  ne 

(x,y,nx,ny, button) 

get  mouse  location  using  a  line 

156 

R_get.locatioa_with_  pointer 

(nx,ny, button) 

get  mouse  location  usng  pointer 

156 

R_get_text_box 

(text,  top,  bottom,  left,  right) 

get  text  extents 

156 

U_move_abs 

lx,y) 

move  cuirent  location 

150 

R_mDve_nel 

(dx,dy) 

move  cunent  location 

151 

ILopen_driver 

0 

initialize  graphics 

148 

R_polydots_abs 

(x,y,num) 

draw  a  series  of  dots 

152 

R.polydots_rei 

(x,y,num) 

draw  a  series  of  dots 

152 

Fi_polygoa_abs 

(x,y,num) 

draw  a  closed  polygon 

152 

R_polygon_nel 

(x,y,num) 

draw  a  closed  polygon 

153 

R_polyline_abs 

(x,y,num) 

draw  an  open  polygon 

153 

ILpolyline_rrl 

(x,y,num) 

draw  an  open  polygon 

153 

U_iasOer 

(num,nnaws,withzero, raster) 

draw  a  raster 

154 

l<_nest'Ccolor 

(red,  green,  blu,  num) 

define  single  color 

149 

U^teseH'olois 

(min,  nnax, red, green, blue) 

define  multiple  colors 

149 

U_RGB_c'ol<)r 

(red,green,blue) 

select  color 

150 

U_R(JR_r.iKtfr 

(num,nnaws,red,green,blue,withzen>) 

draw  a  raster 

154 

K  ^.-ciixTubot 

( ) 

bottom  of  screen 

150 

U.scRi'rulort 

() 

screen  left  edge 

150 

U 

() 

screen  right  edge 

150 

K  St' II  I  n, top 

0 

top  of  screen 

150 

U  ;U_tolor 

(red,green,blut') 

initialize  graphics 

154 

U  st'L-" iihIou 

( top,bottom,lcft,  right) 

set  text  clipping  window 

155 

It  st;uitla)d_color 

(color) 

select  standard  color 

150 

U^tfxLsizc 

(width,  height) 

set  text  size 

155 

R.tfxt 

(texO 

1  write  text 

156 

Index  to  Rasta*  Graphics  Libraiy 
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Index  to  Roiiio  library 


Here  is  an  index  of  Rowio  Library  routines,  with  calling  sequences  and  short  function 
descriptions. 


Rowio  Library 


routiive 

Darameters 

descriotion 

page 

rowio_filet» 

(r) 

get  file  descriptor 

176 

towio_flush 

(r) 

force  pending  updates  to  disk 

176 

rDwio_foi^t 

(r,  n) 

forget  a  row 

175 

rDwio_get 

(r,  n) 

read  a  row 

175 

rDwio_put 

(r,  buf,  n) 

write  a  row 

176 

rDwio_neleaae 

(r) 

free  allocated  memory 

176 

rowio_3etup 

(r,  fd,  mows,  len,  getrow,  putrow) 

configure  rowio  structure 

174 

Index  to  Rowio  Library 
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Here  is  an  index  of  S^^nent  Library  routines,  with  calling  sequences  and  short 
function  descriptions. 


Segment  Libraiy 


routine 

DarameteiB 

descriotion 

page 

segmentJiush 

(seg) 

flush  pending  updates  to  disk 

182 

aegmentJbrmat 

(fd,  nrows,  ncols,  stows,  acols,  len) 

foimat  a  segment  file 

180 

9egment_get_row 

(s^,  buf,  row) 

read  row  from  segment  file 

182 

segmenlLget 

(s^,  value,  row,  col)  i 

get  value  from  segment  file 

181 

segnient_init  ■ 

(s^,  fd,  naegs) 

initialize  segment  structure 

181 

9egment_put_row 

(seg,  buf,  row) 

write  row  to  segment  file 

181 

segmenLput 

(seg,  value,  row,  col) 

put  value  to  segment  file 

182 

segmentjelease 

(aeg) 

free  allocated  memoiy 

183 

Index  to  Segment  Library 
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Iiidex  to  Vask  library 


Here  is  an  index  of  Vask  Libiary  routines,  with  calling  sequences  and  short  function 
descriptions. 


Vask  Libraiy 


routine 

oarameters 

deac  notion 

-fiage 

V_call 

0 

interact  with  the  user 

189 

V_clear 

0 

initialize  screen  description 

188 

V_const 

(value,  type,  row,  col,  len) 

define  screen  constant 

188 

V_float_acc  uracy 

(num) 

set  number  of  decimal  places 

189 

(text) 

change  ctri-c  message 

190 

VJntrpLok 

() 

allow  ctri-c 

189 

VJine 

(num,  text) 

add  line  of  text  to  screen 

188 

V_ques 

(value,  type,  row,  col,  len) 

define  screen  question 

188 

Index  to  Vask  Library 
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end  level  one  vector 

access 

digJiiiiO 

125 

initialize  level  one  vector 

access 

digjnid) 

126 

end  level  two  vector 

access 

dig_P_fini() 

128 

initialize  level  two  vector 

access 

dig_PJnit( ) 

128 

get  the 

active  window 

G_gelLset_window( ) 

79 

set  the 

active  wiivdow 

G_set_window( ) 

79 

number  of  columns  in 

active  window 

G_window_cols( ) 

78 

number  of  rows  in 

active  window 

G_window_rows( ) 

78 

add  cell  file  name  to  display  list 

D_3et.celLname( ) 

162 

add  command  to  window  display  list 

D_add_tojist( ) 

161 

add  file  name  to  Ref  structure 

Ladd_file_tD_giDup_ref( ) 

141 

add  line  of  text  to  screen 

VJineO 

188 

add  r>ew  control  point 

Lnew_controLpoint( ) 

143 

allocate  a  cell  buffer 

G_allocate;_celLbuf( ) 

86 

copy  string  to 

allocated  merrtory 

G_store() 

114 

free 

allocated  merrBry 

rowioLjeleasef ) 

176 

free 

allocated  memory 

segmenLieleasef ) 

183 

memory 

allocation 

G_calloc( ) 

76 

memory 

cdlocation 

G_malloc( ) 

76 

memory 

allocation 

G_iealloc( )  • 

76 

allow  ctri-c 

VJntrpt_ok( ) 

189 

distance  to 

arc 

dig_chEck_dist< ) 

132 

read 

are 

digJLreadJinef ) 

130 

read  next 

are 

dig_P_read_next_line( ) 

131 

prune  a  dense 

are 

dig_prutie{ ) 

135 

read 

are 

digjleadjinef ) 

133 

get  next 

are 

dig_nead_next.line( ) 

126 

write 

are 

dig_Wtite_liiie< ) 

133 

get 

arc  bounding  box 

dig_boui*Lbox( ) 

135 

get 

anc  bounding  box 

dig_P_get_line_bbox( ) 

131 

get  next 

arc  by  type 

dig_teatLnext_line_type( ) 

126 

get 

are  category  attribute 

digj’_line_att( ) 

131 

read 

are  in  box 

dig_read_line_m_box( ) 

127 

limit 

arc  search  in  box 

digJniLboxf ) 

127 

find 

ae  with  point 

dig_point_to_line( ) 

132 

get  number  of 

aes 

dig_P_numJines( ) 

130 

point  in 

ava 

dig_pointJi;_area( ) 

132 

get 

aea  bounding  box 

dig_P_geLarea.bbox( ) 

130 

get 

aea  category  attribute 

dig_P_area_att( ) 

130 

get 

ava  polygon 

digJP_get_area( ) 

129 

get 

iirva  polygon 

djg_P_geLatea_xy( ) 

129 

find 

ava  with  point 

dig_point_to_atea( ) 

132 

get  number  of 

iireas 

dig_P_num_aieas( ) 

129 

earth  to 

array  (east) 

D_u_to_a-Col( ) 

163 

earth  to 

array  (north) 

D_u_to_a_row( ) 

163 

anav  to  screen  (column) 

D_a_to_cLcol( ) 

163 

aray  (o  screen  (rrrw) 

D_a.to_d_row( ) 

165 

•senw-n  to 

arav  (x) 

D_d_tD_a_col( ) 

16i 
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screen  to 

array  (y) 

D_cLto_a_row( ) 

164 

ask  a  yeatoo  question 

G_yes() 

118 

make 

aspect  colors 

G_inake_a6pect_colois( ) 

97 

asagn/retrieve  current  map  window 

D_check_in^wiixiow( ) 

160 

get  area  categoiy 

attribute 

dig_P_aiea_att( ) 

130 

get  arc  categoiy 

attribute 

dig_P_line_att( ) 

131 

bottom  of  screen 

R_9cieen_bot( ) 

150 

get  arc 

bounding  box 

dig_bouixLbox( ) 

135 

get  area 

bounding  box 

digJLget_area^bbox( ) 

130 

get  arc 

bourxting  box 

dig_P_get_line_bbox( ) 

131 

get  arc  bounding 

box 

dig_bound_box( ) 

136 

limit  arc  search  in 

box 

digJnit_box( ) 

127 

get  area  bounding 

box 

digJ*_get_area_bbox( ) 

130 

get  arc  bounding 

box 

dig_P_get_line_bbox( ) 

131 

read  arc  in 

box 

dig_read_line_iiLbox( ) 

127 

fill  a 

box 

R_box_abs() 

151 

fill  a 

box 

R_box_rcl( ) 

151 

get  mouse  location  using  a 

box 

R_get_location_with_box( ) 

167 

allocate  a  cell 

buffer 

G_allocate_celLbuf( ) 

86 

zero  a  cell 

buffer 

G_zero_celLbuf( ) 

86 

query 

cartogrsphic  projection 

G_pit>jection() 

80 

query 

cartographic  projection 

G_projection_name( ) 

80 

query 

cartographic  zorte 

G_zone() 

80 

convert  string  to  lower 

case 

G_tolcase( ) 

114 

convert  string  to  upper 

case 

G_tDucase( ) 

114 

getaea 

eatery  attribute 

dig_P_arEa_attt') 

130 

get  arc 

category  attribute 

dig_P_line_att( ) 

131 

get  a 

category  color 

G_get.color( ) 

95 

set  a 

category  color 

G_set_color( ) 

96 

read  cell 

categoiy  file 

G_reacLcat^ ) 

91 

read  vector 

category  file 

G_read_veclDr_catB( ) 

105 

write  cell 

categoiy  file 

G_write_catB( ) 

92 

write  vector 

category  file 

G_write_vector_catst ) 

106 

get  a 

categoiy  label 

G_get_cat< ) 

93 

set  a 

categoiy  label 

G_9et^cat( ) 

94 

get  tide  from 

category  structure 

G_get_cats_titie( ) 

93 

initialize 

category  structure 

G_inil_cals( ) 

93 

set  tide  in 

category  structure 

G_seLcats_tide( ) 

94 

free 

category  structure  memory 

G_free_cats( ) 

94 

allocate  a 

cell  buffer 

G_allocate_cell_buf( ) 

86 

zero  a 

cell  buffer 

G_zero_celLbuf{ ) 

86 

read 

cell  eatery  file 

G_read_cats< ) 

91 

write 

cell  category  file 

G_wrile_cats( ) 

92 

prompt  for  existing 

cell  file 

G_ask^cellJn_mapsett  ) 

81 

prompt  for  new 

cell  file 

G_ask_celLnew  ( ) 

81 

pnimpi  for  existing 

cell  file 

G_asli_celLold( ) 

81 

dost'  a 

cell  file 

G_clo.sc_cell( ) 

89 

find  a 

cell  file 

G_fiixLcell2( ) 

82 

find  a 

cell  file 

G_firKl_cell( ) 

82 

read  a 

cell  file 

G_get_map_row( ) 

87 

open  an  existing 

cell  file 

G_opcn_celLold( ) 

8;5 

unopen  a 

cell  file 

G_  unopen_cell( ) 

89 

retric\'e 

cell  file  name 

D_gpt_celLname( ) 

162 

itld 

cell  file  name  to  display  list 

D_HeLcelLnamc< ) 

162 
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open  a  new 

cell  file  (random) 

0_open_cell_new_rarKk)m( ) 

86 

write  a 

cell  file  (random) 

G_put_nv^_row_rantk)m( ) 

88 

open  a  new 

cell  file  (sequential) 

G_open_celLnew( ) 

84 

write  a 

cell  file  (sequential) 

G_put_map_row( ) 

88 

open  a  new 

cell  file  (uncompressed) 

G_open_cfelLnew_uncompressed( ) 

85 

read  a 

cell  file  (without  masking) 

G_get_m^_row_nomasfc( ) 

87 

read  the 

cell  header 

G_get_cellhd( ) 

90 

write  the 

cell  header 

G_put_cellhd( ) 

90 

read 

cell  history  file 

G_teaiLhistoty( ) 

98 

write 

cell  history  file 

G_writB_histoiy( ) 

99 

read 

cell  range 

G_iBad_range( ) 

99 

write 

cell  range 

G_write_range( ) 

100 

get 

cell  title 

G_get.cel!_titie( ) 

92 

change 

cell  title 

G_put_celLtitie( ) 

92 

change  cell  title 

G_pulLcelLlilie( ) 

92 

change  ctri-c  message 

V_mtrpt^msg( ) 

190 

change  error  handling 

G_9et_error_routine( ) 

66 

return  interrupt 

char 

G_intr_char< ) 

117 

printable  version  of  control 

character 

G_unclri( ) 

114 

check  for  legal  database  file  names 

G_legal_filename< ) 

72 

create  a  protected 

child  process 

G_fotk( ) 

116 

choose  font 

R_font( ) 

156 

clear  window  displ^  lists 

D_clear_witxlow( ) 

161 

clears  information  about  current  window 

D_clear_window( ) 

161 

clip  coordinates  to  window 

D_clip( ) 

166 

set  terrt 

clipping  window 

R_set.wii>dow( ) 

156 

close  a  cell  file 

G_close_cell( ) 

89 

temporary 

close  vector  map 

dig.P_tmp_close( ) 

128 

draw  a 

closed  polygon 

R_polygon_abs( ) 

152 

draw  a 

closed  polygon 

R_polygoa.rel( ) 

153 

reopen 

closed  vector  m^ 

dig_P_tmp_open( ) 

128 

get  a  category 

color 

G_geti_color( ) 

96 

set  a  category 

color 

G_set_color( ) 

96 

select 

color 

R_coloK ) 

149 

define  single 

color 

R_reset_color( ) 

149 

select 

color 

R_RGB_color( ) 

150 

select  standard 

color 

R_standard_color( ) 

150 

color  name  to  number 

D_lranslate_color( ) 

167 

make 

color  ranp 

G_make_color_ramp( ) 

97 

initialize 

color  structure 

G_init_colors( ) 

96 

free 

color  structure  memory 

G_free_colors( ) 

96 

read  map  layer 

color  table 

G_tEad_colors( ) 

94 

write  map  layer 

color  table 

G_write_colors( ) 

95 

select  fixed 

color  tabic 

R_color_tablc_ftxed( ) 

149 

select  floating 

color  table 

R_color_table_float( ) 

149 

make 

color  wave 

G_make_color_wave( ) 

97 

make  aspect 

colors 

G_msi4e_a6pecGcolors( ) 

97 

make  rainbow 

colors 

G_make_rdinbow_colots( ) 

97 

rrtake  lartdom 

colors 

G_make_rdrKiom_colors( ) 

98 

malvc  ted, yellow, green 

colors. 

G_tnd<e_tecLyei_grn( )’ 

98 

define  multiple 

colors 

R_n'9et,_colorB( ) 

149 

set 

colors  in  driver 

r)_ie3et_colors( ) 

167 

iin'.iy  to  screen 

(column) 

D_a_to_d_tol( ) 

1&3 

numbei-  of 

columns  in  active  window 

G_wirKlow_tols( ) 

78 
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nm  a  shell  level 

command 

116 

parae 

command  line 

G_paiw_command( ) 

109 

command  line  usage  message 

G_parse_command_usage( ) 

111 

add 

command  to  window  di^ay  list 

D_akLtD Jisd ) 

161 

print  percent 

complete  messages 

G_percent( ) 

117 

concatentate  strings 

G.strcat() 

113 

configure  rowio  structure 

rowio_9eti^ ) 

174 

define  screen 

constant 

V_const( ) 

188 

print  warning  message  and 

continue 

G_waTiing( ) 

64 

printable  version  of 

control  character 

G_unctrl( ) 

114 

add  new 

control  point 

Lnew_contioLpoint( ) 

143 

read  group 

control  points 

Lget_conttoLpoints( ) 

143 

write  group 

control  points 

Lput_contioLpoinls( ) 

144 

initialize 

conversions 

D_do_conversions( ) 

162 

convert  string  to  lower  case 

G_tolcase( ) 

114 

convert  string  to  upper  case 

G_touca9e( ) 

114 

retrieve  current  window 

coordinates 

D_get_screen_wirxiow( ) 

160 

clip 

coordinates  to  vrindow 

D_clip( ) 

166 

copy  Ref  lists 

Liransfer_gioup_ref_file( ) 

141 

copy  string  to  allocated  memory 

G_stote() 

114 

copy  strings 

G_strcp!yO 

113 

copy  strings 

G_sfnx;pv( ) 

113 

create  a  lock 

lock_file( ) 

169 

create  a  protected  child  process 

G_fork() 

116 

create  trew  graphics  window 

D_new_windowl ) 

160 

allow 

ctri-c 

V_intrpt_ok( ) 

189 

change 

ctri-c  message 

V_inlrpLnnsg( ) 

190 

get  a  line  of  input  (detect 

ctrl-z) 

G_get8() 

117 

current  date  and  time 

G_date() 

117 

identify 

current  graphics  wmdow 

D_get.cur_windl ) 

160 

set 

current  graphics  window 

D_set;_cur_wind( ) 

160 

move 

current  location 

R_move_abs( ) 

150 

move 

current  location  . 

R_mDve_rel( ) 

151 

current  location  ditectoiy 

G_location_path( ) 

67 

current  location  name 

GJocationf ) 

66 

assign/retrieve 

current  map  wirxlow 

D_check_rnap_window( ) 

160 

current  mapset  name 

G.mapsetf ) 

66 

give 

current  time  to  window 

D_timestanip( ) 

161 

clears  information  about 

cunent  window 

D_clear_wirxk>w( ) 

161 

erase 

current  window 

D_erase_wiixlow( ) 

161 

outlines 

cunvnt  wirxlow 

D_show_wTrxlow( ) 

160 

retrieve 

current  wirxlow  coordin.ites 

D_get_scieen_wirxiow( ) 

160 

resets 

current  window  position 

D_re9et_scteen_wirxiow(  i 

161 

top  level 

database  directory 

G_gisdbase( ) 

67 

prompt  loi-  existing 

database  file 

G_askJn_map8eU  ) 

70 

pnrmpt  lor  new 

datiibase  file 

G_ask_new( ) 

ao 

prompt  I'oi  existing 

datiibase  file 

G_a6k_old( ) 

69 

find  a 

database  file 

r._find_file2( ) 

71 

find  a 

database  file- 

G_firxl.file( ) 

71 

open  a  new 

database  file 

G_fopen_newf ) 

74 

open  a  new 

database  file 

G_open_new( ) 

74 

lenrwve  a 

datiibase  file 

G_remDve( ) 

75 

rename  a 

datiibase  file 

G_rename( ) 

75 

open  a 

datiibase  file  for  reading 

G_fopen_old( ) 

73 
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open  a 

dat^)aBe  file  for  reacfing 

G_open_old( ) 

72 

open  a 

database  file  for  tplate 

CLfopea-append( ) 

73 

open  a 

database  file  for  update 

G_open_update( ) 

73 

rht'ck  for  Itynl 

databw  file  names 

0_legal.filenamr( ) 

72 

read  the 

database  window 

G_get_window( ) 

77 

write  the 

database  window 

GLputL.window( ) 

77 

current 

date  and  time 

G_date() 

117 

set  number  of 

decimal  traces 

V_fk)aLaccuiacy( ) 

189 

read  the 

default  window 

(j_get_default_winik)w( ) 

78 

define  multiple  colors 

R_reset.colors( ) 

149 

define  screen  constant 

V_const( ) 

188 

define  screen  question 

V_ques() 

188 

define  angle  color 

R_ieselLcoloK ) 

149 

(xune  a 

dense  arc 

dig_prune( ) 

135 

initialize  screen 

description 

V_cleari ) 

188 

get  file 

descriptor 

rowio_fileno( ) 

176 

get  a  line  of  input 

(detect  ctrl-z) 

G_getB() 

117 

cop  level  program 

directory 

G_gisba8e( ) 

66 

top  level  database 

directory 

G_gisdbaae( ) 

67 

user's  home 

directory 

G_hDme( ) 

117 

current  location 

directory 

GJocatioh_path( ) 

67 

force  pending  updates  to 

disk 

rowio_flush( ) 

176 

flush  pettding  updates  to 

disk 

segmenLflusht ) 

182 

add  command  to  window 

display  list 

D_add_to_list( ) 

161 

add  cell  file  name  to 

display  list 

D_9et_celLname( ) 

162 

clear  window 

display  lists 

D_clear_window( ) 

161 

di^ay  vector  header  information 

dig_print.header( ) 

125 

distance  to  ae 

dig_check_dist( ) 

132 

distance  to  line-s^ftnent 

dig_distance2_point_to_line( ) 

134 

distance  to  line-segment 

digjty_distance2_point_to_line( ) 

i;i5 

does  group  exist? 

Lfind_group( ) 

139 

draw  a  series  of 

dots 

FLpolydots_abs( ) 

152 

draw  a  series  of 

dots 

R_polydots_reU  ) 

152 

draw  a  closed  polygon 

R_polygoruabs( ) 

152 

draw  a  closed  polygon 

R_polygort_rel( ) 

153 

draw  a  raster 

R_raster< ) 

154 

draw  a  raster 

R_RGB_t-dSier-( ) 

154 

draw  a  series  of  dots 

R_po)ydots_abs(  ) 

152 

draw  a  series  of  dots 

R_polydots_rel(  i 

152 

cli:aw  an  open  polygon 

R_polyline_abs(  ) 

153 

draw  an  open  polygon 

R^polyline_rel( ) 

153 

draw  line 

R_cont_abs( ) 

151 

draw  line 

R_cont_rel( ) 

151 

HL*i  colors  in 

driver 

D_reseLcolois(  ) 

167 

earth  to  array  (east! 

D_U_tD_£L.C0l(  1 

163 

earth  to  am^  (north) 

D_u_to_a_row(  i 

16.3 

earth  to  screen  (east) 

D_tLto_d_col(  1 

164 

earth  to  screen  (north) 

D_tLto_d_row(  ' 

163 

screen  to 

earth  (x) 

D_cLto_u_col(  I 

164 

screen  Ur 

earth  (y) 

D_cLto_u_row( ) 

164 

earth  to  array 

(east) 

D_u_to_a_col( ) 

163 

earth  U)  screen 

(east) 

D_iLto_cl_col( ) 

164 

.'<teen  left 

edge 

R_3creen_lcrt(  ) 

150 

sc  ii'en  light 

edge 

R_screen_rite(  ) 

150 
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end  level  one  vector  access 

digJiniO 

126 

end  level  two  vector  access 

dig_P_fini( ) 

128 

query  GRASS 

environment  variable 

G _ getenvf ) 

67 

query  GRASS 

environment  variable 

G_getenv() 

67 

set  GRASS 

environment  vatiaUe 

G _ setenvf ) 

67 

set  GRASS 

environment  variable 

G_9etenv( ) 

67 

erase  current  window 

D_era8e_window( ) 

■  161 

erase  screen 

R,_eraBe() 

152 

sleep  on 

error? 

G_sleep_on_errort ) 

66 

change 

error  handling 

G_set.error_roufine( ) 

66 

reset  itonnal 

error  handling 

G_unset_erTOr_routii>e( ) 

65 

print 

error  message  and  exit 

G_fataLem)r( ) 

64 

does  group 

exist? 

Lfind_group( ) 

139 

prompt  for 

existing  cell  file 

<i_ask_cell_in_mapBet( ) 

81 

prompt  for 

existing  cell  file 

G_aslc.celLold( ) 

81 

open  an 

existing  cell  file 

G_open_celLold( ) 

83 

prompt  for 

existing  database  file 

G_askJn_map8et( ) 

70 

prompt  for 

existing  databaae  file 

G_ask_old( ) 

69 

[xompt  for  an 

existing  group 

Lask_gtDup_old( ) 

138 

pronrqit  for 

existing  ate  list  file 

G_aslt.sites_in_mapeetf ) 

106 

prompt  for 

existing  site  list  file 

G_ask_sitES_old( ) 

106 

open  an 

existing  site  list  file 

G_fopen_ates_old( ) 

107 

prompt  for  an 

existing  vector  file 

G_aBk_vector_in_mapBet( ) 

101 

prompt  for  an 

existing  vector  file 

G_aslevector_old( ) 

101 

open  an 

existing  vector  file 

G_fopen_vector_old( ) 

103 

print  error  message  and 

exit 

G_fatal_erTOr( ) 

64 

get  text 

extents 

R_get_text_box( ) 

156 

rewind  vector 

file 

(iig_rewirxi( ) 

125 

prompt  for  existing  cell 

file 

G_ask_cellJn_mapBetl ) 

81 

prompt  for  new  cell 

file 

G_ask.cell_new( ) 

81 

prompt  for  existing  cell 

file 

G_aBk.cel]_old( ) 

81 

prompt  for  existing  database 

file 

G_ask_in_mapeetf ) 

70 

prompt  for  new  database 

file 

G_aBk_new( ) 

69 

prompt  for  existing  database 

file 

G_ast.oid( ) 

69 

prompt  for  existing  ate  list 

file 

G_ask_sites_in_mapset( ) 

106 

prompt  for  new  ate  list 

file 

G_ask_sitES_new( ) 

106 

prompt  for  existing  ate  list 

file 

G_ask_sitES_old( ) 

106 

prompt  for  an  existing  vector 

file 

G_ask_vector_it\_mapeet( ) 

101 

prompt  for  a  new  vector 

file 

G_ask-vector_new( ) 

101 

prompt  for  an  existing  vector 

file 

G_ask_vector_oid( ) 

101 

close  a  cell 

file 

G_close_cell( ) 

89 

firxl  a  cell 

file 

G_ruxLccll2( ) 

82 

find  a  cell 

file 

0_find_ceIl( ) 

82 

find  a  database 

file 

G_find_file2( ) 

71 

find  a  database 

file 

G_fincLfile( ) 

71 

find  a  vector- 

file 

(J_firtd_vecU)r2( ) 

102 

firxl  a  vector- 

file 

G_riixl_vecU)r( ) 

102 

open  a  new  database 

file 

(J_fopen_n<.-w( ) 

74 

open  a  new  ate  list 

file 

G_foperusites_newl ) 

107 

open  ai  existing  site  list 

file 

G_fopen_sjtcs_old( ) 

107 

open  a  new  vector 

file 

G_fopen_vi>ctor_new( ) 

104 

open  an  existing  vector- 

file 

G_fopen_vettor_old(  ) 

103 

read  a  cell 

file 

fJ_get._map_row( ) 

87 

read  ate  list 

file 

(>_Wet_sitD(  t 

107 
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recIasB 

file? 

GJsjeclassC ) 

91 

open  an  existing  cell 

file 

G_open_celLold( ) 

83 

open  a  new  database 

file 

Ci,open_new( ) 

74 

write  site  list 

file 

G_putJite() 

108 

read  cell  category 

file 

OjeacLcalsO 

91 

read  cell  history 

file 

GjeadJiistorjd ) 

98 

read  vector  category 

file 

G_read_vector_catB( ) 

106 

remove  a  database 

file 

G_rennove<) 

75 

rename  a  database 

file 

G_rename() 

76 

unopen  a  cell 

file 

G_unDpen_cell( ) 

89 

write  cell  category 

file 

G_write_catB( ) 

92 

write  ceQ  history 

file 

G_writejiistory( ) 

99 

write  vector  category 

file 

G_wTitB_vectDr_eats( ) 

105 

read  group  REF 

file 

Lget_grot4>_ref( ) 

140 

read  subgroup  REF 

file 

Lget_subgroup_ref( ) 

140 

write  group  REF 

file 

I_put_groi4)_ref( ) 

140 

write  subgroiq)  RB^' 

file 

Lput_subgrDup_ref( ) 

140 

format  a  segment 

file 

segmenLformad ) 

180 

get  value  from  segment 

file 

*gment_get<) 

181 

read  row  from  segment 

file 

9egmer^Lget_row( ) 

182 

put  value  to  segment 

file 

s^meriLputO 

182 

write  row  to  s^;ment 

file 

aegment_put_row( ) 

181 

get 

file  descriptor 

rowio_filer»( ) 

176 

open  a  database 

file  for  reading 

G_fopen_old() 

73 

open  a  database 

file  for  reading 

G_open_old() 

72 

open  a  database 

file  for  update 

G_fopen_a|)perxl( ) 

73 

open  a  database 

file  for  update 

G_operuupdalE( ) 

73 

retrieve  cell 

file  nane 

D_get_celLname( ) 

162 

prompt  for  any  valid 

file  name 

G_aBk_any( ) 

70 

returns  a  teruxrrary 

file  nane 

G_tempfile( ) 

108 

add  cell 

file  nane  to  di^ay  list 

D_9eiLcelLnarre( ) 

162 

add 

file  name  to  Ref  structure 

Ladd_file_tD_group_ref( ) 

141 

check  for  legal  datahasp 

file  nanes 

Gjegal_filename( ) 

72 

open  a  new  cell 

file  (random) 

G_opetuceU_new_xandoin( ) 

as 

write  a  cell 

file  (random) 

G_ixjt_map_rDw_iarxiom( ) 

88 

open  a  new  cell 

file  (sequential) 

G_opetucelLnew( ) 

84 

write  a  cell 

file  (sequential ) 

G_put_map_row( ) 

as 

open  a  new  cell 

file  (uncompressed) 

G_operucelLnew_uncomptessed( ) 

85 

read  a  cell 

file  (without  masldng) 

G_get_map_rDw_nomask( ) 

87 

fill  a  box 

R_box_ab^ ) 

151 

fill  a  box 

R_box_rcl( ) 

151 

find  a  cell  file 

G_fiixLcell2( ) 

82 

find  a  cell  file 

G_fincLcell( ) 

82 

find  a  database  file 

G_find_file2( ) 

71 

fiixi  a  dat^oase  file 

G_fincLfile( ) 

71 

find  a  vector  tile 

G_find_vectDi2( ) 

102 

find  a  vector  file 

G_find_vector( ) 

102 

firx)  arc  with  point 

dig_point_to_line( ) 

132 

find  area  with  point 

dig_point_to_area( ) 

132 

select 

fixed  color  table 

R_color_table_fixed( ) 

140 

select 

floating  color  table 

R_c()lor_table_float( ) 

14‘J 

flush  graphics 

R^flusW ) 

152 

flush  penditrg  updates  to  disk 

segment_ftush( ) 

182 

choose 

font 

iLfonU ) 

155 
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force  pending  updates  to  disk 

rDwio_flush( ) 

176 

forget  a  row 

rowio_fotget( ) 

176 

fonnat  a  segment  file 

segmentLformad ) 

180 

free  allocated  meroory 

rDwio_rdeaBe( ) 

176 

free  allocated  tnenBiy 

segment-releaBef ) 

183 

free  category  stmture  memory 

G_free_cate( ) 

94 

free  color  structure  memoiy 

G_fiBe_color8( ) 

96 

free  Ref  structure 

Lfree_group_refl ) 

142 

ini  tialize 

gis  library 

G_gianit( ) 

64 

give  current  time  to  window 

D_timestamp( ) 

161 

prepare  for  raster 

graphics 

D_cell_draw_9etup( ) 

165 

terminate 

graphics 

R_cloee_driver( ) 

148 

flush 

graphics 

R,_flush( ) 

152 

initialize 

graphics 

R_open_driver< ) 

148 

initialize 

graphics 

R_9et_RGB_color( ) 

154 

identify  current 

graphics  window 

D_get_cur_wind( ) 

160 

create  new 

graphics  window 

D_new_window( ) 

160 

set  current 

graphics  window 

D_aet_cur_wirxl( ) 

160 

query 

GRASS  environrrrent  variable 

G__getEnv() 

67 

query 

GRASS  environment  variable 

G_getenv( ) 

67 

set 

GRASS  environment  variable 

G _ setenvf ) 

67 

set 

GRASS  environment  variable 

G_selBnv< ) 

67 

make  linear 

grey  scale 

G_make_grey_9cale( ) 

97 

prompt  for  new 

group 

Laslc.group_new( ) 

138 

prompt  for  an  existing 

group 

Lask_group_old( ) 

138 

read 

group  control  points 

I_get_controLpoints( ) 

143 

write 

group  control  points 

Lput_controLpoints( ) 

144 

does 

group  exist? 

LfmcLgioupf ) 

139 

prompt  for  any  vaUd 

group  name 

Lask^up_any( ) 

139 

read 

group  REF  file 

Lget^up_ref( ) 

140 

write 

group  REF  file 

LpuUgroup_ref{ ) 

140 

change  error 

harxUing 

G_seLerror_routirK( ) 

65 

reset  normal  error 

handling 

G_unseLerror_routine< ) 

66 

read  vector 

header 

dig_read_heacLbinaty( ) 

134 

write  vector 

header 

dig_writeJ)ea(Lbinay( ) 

134 

read  the  cell 

header 

G_geLcellhd( ) 

90 

write  the  cell 

header 

G_pui_cellhd( ) 

90 

display  vector 

header  information 

dig_prinLheader( ) 

125 

read  cell 

history  file 

G_rc£xl_histDr>’( ) 

98 

write  cell 

history  file 

G_wTitL'_ history! ) 

99 

initialize 

history  structure 

G_shoit_ history! ) 

99 

get 

Hit  RETURN  msg 

G_get.ask^retum_msg! ) 

70 

set 

Hit  RETURN  mag 

G_scU.Tslcretum_nnsg! ) 

70 

user's 

home  directory 

G_home!  ) 

117 

identify  current  graphics  window 

l)_gct_cur_wirxl!  ) 

160 

displ.iv  Ncclor  header 

inl'ormadon 

dig_piinl_header!  ) 

125 

read  target 

information 

I_get_Uugett  ) 

142 

write  target 

information 

LpuLiaigetl ) 

142 

clears 

inform^on  about  current  window 

D^clciii  .window!  ) 

161 

initialize  category  structure 

G.init.cals! ) 

93 

initialize  color  structure 

G_init_colors(  ) 

96 

initialize  conversions 

D  .do_conversions!  ) 

162 

initialize  gis  library 

G_gisiriill  ) 

64 

initialize  graphics 

R_opi'n.fl)iver!  ) 

148 
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initialize  graphics 

R_set_RGB_color( ) 

164 

initialize  history  structure 

G_shortLhi  story  ( ) 

99 

initialize  level  one  vector  access 

digjnid ) 

126 

initialize  level  two  vector  access 

dig_P_init( ) 

128 

initialize  range  structure 

G_imt_range( ) 

1(X) 

initialize  Ref  structunc 

LiniLgroup_ref( ) 

141 

initialize  screen  description 

V_clear( ) 

188 

initialize  segment  structure 

segmenLiniU ) 

181 

get  a  line  of 

input  (detect  ctrl-z) 

G_gets() 

117 

interact  with  the  user 

V_call( ) 

189 

return 

interrupt  char 

G_intr_char( ) 

117 

get  a  category 

label 

G_geLcat( ) 

93 

set  a  category 

label 

G_aet_cat( ) 

94 

read  map 

layer  color  table 

G_read_colors( ) 

94 

write  map 

layer  color  table 

G_wTite_colors( ) 

95 

remove 

leading/training  white  space 

<Lstrip( ) 

114 

screen 

left  edge 

R^screeruleftt ) 

150 

check  for 

legal  database  file  names 

G_legal_filename(  i 

72 

run  a  shell 

level  command 

G_^stem( ) 

116 

top 

level  database  directory 

G_gisdbase( ) 

67 

end 

level  one  vector  access 

digjinn ) 

125 

initialize 

level  one  vector  access 

digjriitt ) 

125 

top 

level  program  directory 

G_gi*ase( ) 

66 

end 

level  two  vector  access 

dig_P_fini( ) 

128 

initialize 

level  two  vector  access 

dig_P_init( ) 

128 

initialize  gis 

library 

G_gianit< ) 

64 

limit  arc  search  in  box 

dig_iniLbox( ) 

127 

parse  command 

line 

G_parse_command( ) 

109 

draw 

line 

R_cont,abs( ) 

151 

draw 

line 

R^cont_iel( ) 

151 

get  mouse  location  using  a 

line 

R_geUocation_with_line( ) 

156 

get  a 

line  of  input  (detect  ctrl-z) 

G_gets( ) 

117 

add 

line  of  text  to  screen 

V_line( ) 

188 

commarKl 

line  usage  message 

G_parse_command_usage( ) 

111 

malcc 

linear  grey  scale 

G_make_grey_scale( ) 

97 

distiince  to 

line-segment 

dig_distance2_polni_lo_linc(  ) 

i;)4 

distance  to 

linc-segrtKnt 

digj(y_distance'2_|x>int_to_lme( ) 

135 

;tdd  comrriiind  to  window  display 

list 

U_add_to_list( ) 

161 

add  cell  lile  name  to  display 

list 

D_set_celLname(  ) 

162 

prompt  for  existing  site 

list  file 

(Lask-sites_in_ma(>ieit  ) 

106 

prompt  for  new  site 

list  lile 

G_ask_sites_new( ) 

106 

prompt  for’ existing  site 

list  lile 

G_ask_sites_old( ) 

106 

open  a  new  site 

list  file 

G_fopen_sites_new(  i 

107 

opj'n  an  existing  site 

list  tile 

(Lfoperusites_old(  i 

107 

read  site 

list  tile 

G_geL.sile{ ) 

107 

wnte  site 

list  file 

G_put_siie< ) 

108 

clear  window  display 

lists 

l)_clcar_window(  ) 

161 

copy  Itef 

lists 

LirarBfer_group_ier_rile( ) 

141 

move  c  urrent 

location 

R_move_abs( ) 

150 

inove  ( unent 

locaUon 

R_move_rel( ) 

151 

cunvnt 

location  directory 

G_location_path(  ) 

67 

( unent 

localion  name 

<I_locabon( ) 

66 

loc.iiion  trlJe 

<  ;_mynaine(  ) 

66 

gel  mouse' 

location  using  a  box 

lLgeUix:ation_\Mih_b<)x(  i 

157 
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get  mouse 

location  using  a  line 

R_getJocalion_with_line( ) 

166 

get  mouse 

location  using  pointer 

R_gBtJocatior\_witt\_pointEK ) 

166 

11 

IlM'k 

lock.fllc( ) 

ia‘) 

remove  a 

lock 

unlock_file<) 

170 

convert  string  to 

lower  case 

G_tolcaBe( ) 

114 

temporay  close  vector 

map 

dig_P_tmp_clo8e( ) 

128 

reopen  closed  vector 

map 

dig_P_tmp_opm( ) 

128 

read 

map  layer  color  table 

G_r2ad_colois( ) 

94 

write 

l^r  color  table 

G_wrilE_colors( ) 

96 

assignAetrieve  current 

map  window 

D_check_map_  window! ) 

160 

current 

mapset  name 

G_map8et() 

66 

read  a  cell  file  (without 

masking) 

G_get_map_row_nDmask( ) 

87 

free  category  structure 

memory 

G_fiee_calB( ) 

94 

free  color  structure 

memory 

G_frBe_colors( ) 

96 

copy  string  to  allocated 

memory 

G_stote< ) 

114 

free  allocated 

menwry 

rowio_tEleaBe( ) 

176 

free  allocated 

memory 

segmenUreleaset ) 

183 

memory  allocation 

G_calloc( ) 

76 

memory  allocation 

G_malloc( ) 

76 

memory  allocation 

G_realloc() 

76 

pop-up 

menu 

D_popup( ) 

166 

command  tine  usage 

message 

G_patse_command_usage< ) 

111 

change  ctri-c 

mess^ 

V_intrpt_msg( ) 

190 

print  warning 

mess^  and  continue 

G_waming<) 

64 

print  error 

message  and  exit 

G.fataLerrort ) 

64 

print  percent  complete 

messages 

G_peTcent( ) 

117 

get 

mouse  location  using  a  box 

R_^t_location_with_box( ) 

157 

get 

mouse  location  using  a  line 

R_geUocation_with_line( ) 

156 

get 

mouse  location  using  pointer 

R_get_locatiort.with_pointEr< ) 

156 

move  current  location 

R_mDve_ab8( ) 

150 

move  current  location 

R_move_reI( ) 

151 

get  Hit  RETURN 

msg 

G_get_ask.retum_inBg( ) 

70 

set  Hit  RETURN 

msg 

G_9et._ask_retum_msg( ) 

70 

define 

multiple  colors 

RjeseLcolois! ) 

149 

retrieve  cell  file 

name 

D_get.cell_name( ) 

162 

prompt  for  any  valid  file 

name 

G.ask^anyl ) 

70 

current  location 

naiTx; 

G_localion( ) 

66 

cumenl  mapset 

name 

G_mapeet( ) 

66 

return  program 

name 

G_program_name( ) 

118 

tviums  a  temporary  file 

naiTx- 

G_tEmpfile( ) 

108 

user's 

naiTW 

G_whoami( ) 

118 

prompt  for  any  valid  group 

name 

LaEk^^up_any( ) 

139 

add  cell  file 

name  to  display  list 

D_set_celLname( ) 

162 

color 

name  to  number 

D_translalE_color( ) 

167 

add  file 

narrv  to  Ref  structure 

Ladd_file_to_group_ref( ) 

141 

check  lor  legal  database  file 

namL-s 

G_legal_filename( ) 

72 

reiitl 

next  arc 

dig_P_ieacLnext_line( ) 

131 

get 

nexi  arc 

dig_read_iKxUine( ) 

126 

gel 

nexi  arc  by  type 

dig_reaid_next_line_type( ) 

126 

rewind 

next- arc  pointer 

digJP_rewind( ) 

131 

reset 

normal  em>r  handling 

G_unset_error_routine( ) 

65 

e;irth  to  arrav 

(north) 

D_u_to_a_row( ) 

163 

caith  to  scieen 

(north) 

D_u_to_d_row( ) 

16.3 

color  niirrx'  in 

nuintx'r 

D_lranslate_coloK ) 

167 
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get 

number  of  arcs 

dig_P_numJines( ) 

130 

gi't 

number  of  areas 

dig.  P_num_  areas! ) 

129 

number  of  columas  in  active  wirKlow 

Ci_window_cols( ) 

78 

set 

number  of  decimal  places 

V_float._accuracy( ) 

189 

number  of  rows  in  active  window 

G_wiixlow_rows( ) 

78 

open  a  database  file  for  reading 

G_fopen_old( ) 

73 

open  a  database  file  for  reading 

G_open_old( ) 

72 

open  a  database  file  for  update 

G_fopen_append( ) 

73 

open  a  database  file  for  update 

G_open_updatje( ) 

73 

open  a  new  cell  file  (random) 

G_open_celLnew_random( ) 

a5 

open  a  new  cell  file  (sequential) 

G_open_celLnew( ) 

84 

open  a  new  cell  file  (uncompressed) 

G_open_cell_ncw_uncompressed( ) 

85 

open  a  new  database  file 

G_i'open_new( ) 

74 

open  a  new  database  file 

G_open_new( ) 

74 

open  a  new  site  list  file 

G_tbperL_3tes_new( ) 

107 

open  a  new  vector  file 

G_fopen_vt'CtDr_new( ) 

104 

open  an  existing  cell  file 

G_open_celLold( ) 

83 

open  an  existing  site  list  file 

G_fopen_sites_old( ) 

107 

open  an  existing  vector  file 

G_fopen_vector_old( ) 

103 

draw  an 

open  poly^n 

R_polyline_abs( ) 

153 

draw  an 

open  polygon 

li-Polyline_iel( ) 

153 

oudines  current  window 

f)_show_wirxlow( ) 

160 

parse  command  line 

G_parse_command( ) 

109 

force 

pending  updates  to  disk 

iow  io_flush( ) 

176 

(lush 

pending  updates  to  disk 

segmenU.flush( ) 

182 

print 

percent  complete  messages 

G_percent( )  . 

117 

set  number  of  decimal 

places 

V_fioat_accuracy< ) 

189 

find  area  with 

point 

dig_point_to_area( ) 

132 

find  arc  with 

point 

dig_point_to_line( ) 

132 

add  new  control 

point 

I_ncw_contiol_point( ) 

143 

point  in  area 

dig_point_irL.aiea( ) 

132 

rewind  nextrarc 

pointer 

dig_P_iewind( ) 

131 

get  mouse  location  asing 

printer 

li_get_location^with_pointer( ) 

156 

lead  gioup  control 

points 

l_get_controLpoints( ) 

143 

wnte  group  control 

points 

Lput,_control_points< ) 

144 

gel  iirca 

polygon 

dig_P_get_area( ) 

129 

get  aiea 

polygon 

dig.-P_geLarea_xy( ) 

129 

draw  a  closed 

polygon 

R_polygon_abs(  ) 

152 

draw  a  closed 

polygon 

IL)X)lvgon_rel(  ) 

153 

draw  an  open 

polygon 

lt_polyline_abs(  ) 

153 

draw  ;in  open 

polygon 

U_(X)ly|jne_tel(  ) 

153 

pop-up  menu 

1  )_(X)pup( ) 

166 

reseis  current  windov\ 

position 

l)_ieset_screen_ window! ) 

161 

prepare  for  rasU-i  gt'aphits 

l)_cell_draw_setup(  ) 

165 

pnnt  enor  message  and  exit 

(i_fatal_enori  ) 

64 

print  percent  complete  nvssages 

(LteieenU  ) 

117 

print  warning  message  and  continue 

('i_vvaming( ) 

ftl 

printable  version  of  control  character 

(Lunctrlt ) 

114 

cieali'  a  protected  child 

process 

C  lotld  ) 

116 

top  level 

program  ditec  torv 

G_gisbase( ) 

66 

lelum 

program  name 

( piogram_nume( ) 

118 

iliK'i'N  carlogr,if)hi( 

piojc-ction 

( f  (xojcxrtionl ) 

80 

ii'K’iv  ( ailogr.iphu 

jxojc'cuon 

< piojection_namc( ) 

80 

prompt  for  a  m'«  vex- tor  file 

<  f  •6<k_vtx:l<)r_nc“w(  i 

101 

Index  for  Library  SUbnxitJnes 


-268- 


prompt  for  an  existing  group 

Laak..group_old( ) 

pron^  for  an  existing  vector  file 

G_aBk_vector_it\_map8et( ) 

prompt  for  an  existing  vector  file 

G_aak_vector_old( ) 

prompt  for  any  valid  file  name 

G_a8k_any( ) 

prompt  for  any  valid  group  name 

Lask_group_any( ) 

prompt  for  existing  cell  file 

G_aBk_cellJn_map8et( ) 

prompt  for  existing  ceil  file 

G_ask_celLold( ) 

prompt  for  existing  database  file 

G_askJn_map8et( ) 

prompt  for  existing  database  file 

G_a8lL.old( ) 

prompt  for  existing  ate  list  file 

G_ask_sites_in_mapset( ) 

prompt  for  existing  ate  list  file 

G_aBk_sites_old( ) 

prompt  for  new  cell  file 

G_ask_cell_new( ) 

pronapt  for  new  database  file 

G_ask_new( ) 

prompt  for  new  group 

Last.group_new( ) 

prompt  for  new  site  list  file 

G_ask_sites_new( ) 

create  a 

protected  child  process 

G_fork( ) 

prune  a  dense  arc 

dig_prur»e( ) 

put  value  to  segment  file 

segment_put( ) 

query  cartographic  projection 

G_projection( ) 

query  cartographic  projection 

G_projectiott_name( ) 

query  cartographic  zone 

G_zone( ) 

query  GRASS  environment  variable 

G__getenv() 

query  GRASS  environment  varicble 

G_getenv( ) 

ask  ayes/no 

question 

G_yes() 

define  screen 

question 

V_ques( ) 

make 

rainbow  colors 

G_make_tainbow_colots( ) 

make  color 

ramp 

G_make_color_ramp( ) 

open  a  new  cell  file 

(random) 

G_open_celLnewjrandom( ) 

write  a  cell  file 

(random) 

G_put.map_row_random( ) 

make 

random  colors 

G_make_random.colors( ) 

read  cell 

range 

G_tEad_range( ) 

write  ceil 

range 

G_write_range( ) 

initialize 

range  structure 

G_initJ-ange( ) 

update 

range  structure 

G_rDw_update_range( ) 

update 

rairge  structure 

G_update_range( ) 

draw  a 

raster 

R_rastert ) 

draw  a 

raster 

R_RGB_raster( ) 

prepare  for 

raster  graphics 

l)_cell_draw_setup( ) 

render  a 

raster  row 

D_draw_cell_row( ) 

render  a 

taster  row  without  zeros 

D_overlay_celLrow( ) 

read  a  cell  file 

G_get_map_row( ) 

read  a  ceil  file  (without  masking) 

G_get_map_row_nomask( ) 

lead  a  row 

rowio_get( ) 

lead  arc 

dig_P_read_line( ) 

lead  arc 

dig_Read_line( ) 

lead  arc  in  box 

digjead_line_in_box( ) 

lead  cell  category  file 

G_reacLcats( ) 

lead  cell  history  file 

G_tEad_histoty( ) 

lead  cell  range 

G_read_  range! ) 

lead  group  control  points 

Lget_controLpoints( ) 

read  group  RI<)F  file 

Lget_group_ref( ) 

lead  map  layer  color  table 

G_read_colors( ) 

lead  next  arc 

dig_P_rEiid_nexUine(  ) 

lead  row  from  segment  file 

si‘gmenf.geLrow( ) 

-268- 


138 
101 

101 

70 

139 
81 
81 

70 

69 

106 

106 

81 

69 

138 

106 

116 

135 

182 

80 

80 

80 

67 

67 

118 

188 

97 

97 

85 

88 

98 

99 

100 

100 

100 

100 

154 

154 

165 

165 

165 

87 

87 

175 

130 
1.33 
127 
91 

98 

99 
143 

140 
94 

131 
182 


FarmUed  Index  for  Library  StforoUines 


-269- 


-289- 


read  ate  list  file 

GL.get.8ite( ) 

107 

read  subgroup  REF  file 

LgetL.subgro^)_ref( ) 

140 

read  taiget  informadon 

Lget_target( ) 

142 

read  the  cell  header 

G_get_cellhd( ) 

90 

read  the  database  window 

G_get_window( ) 

77 

read  the  dd’ault  window 

G_get.default_  window! ) 

78 

read  vector  category  file 

G_tEad_vector_cats( ) 

106 

read  vector  header 

digjead_head_binaty( ) 

134 

open  a  database  file  for 

reading 

G_fopen_old( ) 

73 

open  a  database  file  for 

reading 

G_open_old( ) 

72 

leclass  file? 

Gjs_ieclas8( ) 

91 

make 

red, yellow, green  colors 

G_m^_re<L^el_gm( ) 

98 

read  group 

REF  file 

Lget.group_tef( ) 

140 

read  subgroup 

REF  file 

Lget.subgroup_ief( ) 

140 

wTite  group 

REF  file 

Lput_group_ref( ) 

140 

rvrite  subgroup 

REl'"  file 

Lput_subgroup_ref( ) 

140 

copy 

Ref  lists 

Ltransfer_group_tef_file( ) 

141 

add  file  name  to 

Ref  structure 

Ladd_file_to_group_ref( ) 

141 

free 

Ref  structure 

Lfree_group_ief( ) 

142 

initialize 

Ref  structure 

LiniLgroup_ref( ) 

141 

remove  a  database  file 

G_remove( ) 

75 

remove  a  lock 

unlock^fileO 

170 

remove  a  window 

D_remove_window( ) 

161 

remove  leading  draining  white  ^>ace 

G_stiip( ) 

114 

remove  unnecessary  white  space 

G_squeeze() 

113 

rename  a  database  file 

G_rename( ) 

75 

rerrder  a  raster  row 

D_draw_cell_row( ) 

165 

render  a  raster  row  without  zeros 

D_overiw_celLrow( ) 

165 

reopen  closed  vector  map 

dig_P_tmp_open( ) 

128 

reset  normal  error  handling 

G_unset_enor_routine( ) 

65 

resets  current  window  position 

D_iEset_screen.window( ) 

161 

retrieve  cell  file  name 

D_get_celLname< ) 

162 

retrieve  current  window  coordinates 

D_get_screen_window( ) 

160 

ictgm  interrupt  char 

G_intr_char( ) 

117 

gel  Hit 

RETI’URN  m^^ 

G_get_ask_tetum_msg( ) 

70 

sol  Hit 

RETI’UliN  msg 

G_8et_ask_retum_msg( ) 

70 

return  program  name 

G_prograiTuname( ) 

118 

returns  a  temporary  file  name 

G_tempfile( ) 

108 

rewind  nextrarc  pointer 

dig_P_rewind( ) 

131 

rewind  vector  file 

dig_rewind( ) 

125 

.an'd\  to  sciwn 

(row) 

D_a_tt)_d_row( ) 

163 

render  a  raster 

row 

D_draw_celLrow( ) 

165 

(bigei  ;i 

low 

rDwio_fotget< ) 

175 

real  a 

row 

rowio_get( ) 

175 

wriu.'  ,1 

row 

rowno_put( ) 

176 

n-.«l 

low  from  segment  file 

segment_get_row( ) 

182 

write 

low  to  .segment  file 

9egment_put_row  ( ) 

181 

render-  a  raster 

row  without  zeros 

D_overiay_celLrt)w( ) 

165 

eonfiguie 

inwio  structure 

rowio_setup( ) 

174 

number  of 

rows  in  active  window 

G_window_rDws(  ) 

78 

run  a  shell  level  commiind 

G_system( ) 

116 

malvf  1 1  near-  giev 

tale 

G_make_grey_scale( ) 

97 

cruse 

f  n-en 

R_eraBe( ) 

152 

Ixrttom  of 

screen 

R_scneerLbotl ) 

150 
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top  of 

screen 

R_scneen_top( ) 

150 

ddd  line  of  text  to 

screen 

V_line( ) 

188 

array  to 

screen  (column) 

D_a^tD_cLcol( ) 

163 

define 

screen  constant 

V_const( ) 

188 

initialize 

screen  description 

V_clear( ) 

188 

earth  to 

screen  (east) 

D_u_to_cLcol(  1 

164 

screen  left  edge 

IL9cieen_left( ) 

150 

earth  to 

screen  (north) 

D_u_to_d_row( ) 

163 

define 

screen  question 

V_ques( ) 

188 

screen  right  edge 

li_scteen_nte( ) 

150 

array  to 

screen  (row) 

D_a_to_d_row  ( ) 

163 

screen  to  array  (x) 

D_d_to_a_col( ) 

164 

screen  to  array  (y) 

I  )_d_to_a_row  ( ) 

164 

screen  to  earth  (x) 

l)_d_to_u_coll ) 

164 

screen  to  earth  (y) 

l)_cLto_u_iDw(  ) 

164 

limit  arc 

search  in  tx>x 

dig_mit_box(  ) 

127 

format  a 

segment  file 

segmeneformati  ) 

180 

get  \  alue  from 

segment  file 

segment_get(  i 

181 

lead  row  from 

segment  tile 

segment^Liowi  ) 

182 

put  value  U) 

segment  file 

segnient.put( ) 

182 

wiite  row  to 

segment  file 

segment_put_row  ( ) 

181 

initialize 

segment  structure 

segment_init( ) 

181 

select  color 

FLcolotd ) 

149 

select  color 

R_RGB_colott ) 

150 

select  fixed  color  table 

R_color_lable_fixed( ) 

149 

SL'lect  lloating  color  table 

R_color_table_float( ) 

149 

st'lect  standard  color 

ILstandarcLcoloii ) 

150 

open  a  new  cell  file 

(sequential) 

(''■_open_celLnew( ) 

84 

write  a  cell  file 

(seiquential) 

G_puL.niap_row( ) 

88 

draw  ii 

series  of  dots 

R_polydots_abs(  ) 

152 

draw  a 

series  of  dots 

lf_polydots_rel( ) 

152 

set  a  category  color 

G_seLcolor<  i 

96 

set  a  catcgoiy  label 

G_i¥Lcat( ) 

94 

set  colors  in  driver 

IJ_reseLcolois(  ) 

167 

si't  cunenl  graphics  window 

l)_a'l_eur_w  ind(  ) 

160 

a  t  OI{.AHS  environiTX'nl  variable 

( J_  _setenv'  ) 

67 

a‘t  (llfASS  environment  variable 

<  l_a-tenvi  i 

67 

a  '  Hu  KCTUHN  msg 

G_a-t_ask_relutTi_msg(  > 

70 

set  number  of  decimal  places 

V_lloat^accui;xyi  ) 

189 

aU  text  clipping  window 

R_a'f_window(  i 

155 

a-i  text  size 

H_lext_size(  ' 

155 

a'l  the  ix  tive  wirxlow 

G_a‘LwirxJowi  i 

79 

a-i  title  m  category  slrtK  tuie 

G_a'UcaLs_tille(  ' 

94 

mn  .1 

shell  U'\el  commiirxl 

<  ;_s\  stem(  ) 

116 

di-lini' 

single  lolor 

H_iea't^c()|oi'  > 

149 

pnimpl  loi  existing 

site  list  file 

( ;_it;lt_siU.u  in^mapseU  i 

106 

pnmipi  Icir  neu 

siU'  list  lile 

<  i-i-t^lv-Sites.neul  ) 

106 

1  in  unfit  lof  existing 

siu.’  list  file 

G_ask_siU.'s_old(  ) 

106 

ofx'ii  a  nev\ 

site  list  lile 

G_l()perusites^new(  ) 

107 

opi’n  .11)  I'xistjng 

site  llsl  lile 

G_foperL.sites_old(  ) 

107 

lead 

site  lisl  tile 

G_geLsile(  ) 

107 

wnte 

site  list  lile 

G-put_site(  ) 

108 

s'l  lexl 

size 

U  text,  size!  ' 

155 

shi'p  on  enor? 

t ’i_skvp_orv  i  noit  i 

tvS 
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nemove  unnecessary  white 

space 

G_aqueeze< ) 

113 

remove  leading/traning  white 

space 

G_sttipO 

114 

select 

standard  color 

R_standaiTLcolor( ) 

160 

copy 

string  to  allocated  memory 

G_store() 

114 

corrvert 

string  to  lower  case 

G_tolcase( ) 

114 

convert 

string  to  upper  case 

G_toucase( ) 

114 

concatentate 

strings 

G_strcalj() 

113 

copy 

strings 

G_sticpy( ) 

113 

copy 

strings 

G_stmcRy( ) 

113 

get  title  from  category 

structure 

G_get_cats_title( ) 

93 

initialize  category 

structure 

G_init_cals( ) 

93 

initialize  color 

structure 

G_init.colois{ ) 

96 

initialize  range 

structure 

G_init_range( ) 

100 

update  range 

structure 

G_rDw_update_range( ) 

100 

set  title  in  category 

structure 

G_set_cats_titie( ) 

94 

initialize  history 

structure 

G_short_hi  story! ) 

99 

update  range 

structure 

G_updatE_range( ) 

100 

add  file  name  to  Ref 

structure 

Ladd_file_to_group_tef( ) 

141 

free  Ref 

structure 

Lftee_group_ref( ) 

142 

initialize  Ref 

structure 

Linit_group_ref( ) 

141 

configure  lowio 

structure 

rowio_setup( ) 

174 

initialize  segment 

structure 

3egiTient_init( ) 

181 

free  category 

structure  memory 

G_free_cats( ) 

94 

free  color 

structure  memory 

G_free_colors( ) 

96 

read 

subgroup  REF  file 

LgeLsubgrDup_ref( ) 

140 

write 

subgroup  REF  file 

Lput_subgrDup:,ref( ) 

140 

suppress  warnings? 

G_supfxess_wamings( ) 

65 

read  map  layer  color 

table 

G_iead_colots( ) 

94 

write  map  layer  color 

table 

G_wiite_colors(  ^ 

95 

select  fixed  color 

table 

R_color_table_rixed( ) 

149 

select  floating  color 

table 

R_color_table_float( ) 

149 

read 

target  information 

LgeLtargett ) 

142 

wTile 

target  information 

LpuLtaigett ) 

142 

temporary  close  vector  map 

dig_P_tmp_close( ) 

128 

tvUims  a 

temporary  file  name 

G_tempfiie( ) 

108 

terminate  graphics 

R_close_dnver( ) 

148 

write 

text 

R_text( ) 

156 

set 

text  clipping  window- 

R_9et_window( ) 

155 

get 

text  extents 

R^Ltext^boxI ) 

156 

set 

text  size 

R_text._size(  ) 

155 

add  line  of 

u-xt  to  screen 

V_line( ) 

188 

gel  cell 

Utie 

(}_getc.celLtitie( ) 

92 

location 

title 

G_mvnamei ) 

66 

change  cell 

title 

G_put_celLtitie( ) 

92 

gel 

ULle  fiom  categoiy  stiuctuiv 

G_get_catB_titlel ) 

93 

set 

UtJe  in  category  sliucUite 

G_9et_cais_lilie< ) 

94 

top  level  dalabine  diixxtoiy 

G_gi9dbaat'(  ) 

67 

top  level  program  cbrirtoty 

G_gisbase(  ) 

66 

top  ol  scieen 

Ii_screen_top( ) 

150 

get  next  air  by 

type 

dig_read_nex1,_line_Lype( ) 

126 

open  a  new  cell  file 

(uncompressed) 

G_open_cclLnew_uncompressed(  ) 

85 

remove 

unnt*cess;uy  white  space 

(jl_squeeze(  ) 

113 

unopen  <i  cell  file 

G_unopen_iell( ) 

89 

open  a  database  file  for 

update 

(i_ropen_appcnd( ) 

73 
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open  a  database  file  for 

update 

G_open_update( ) 

73 

update  range  structure 

G_row_iipdate_range( ) 

100 

i^xiate  range  structure 

G_updatejange( ) 

100 

force  pending 

updates  to  disk 

rowio_fludi( ) 

176 

flush  pending 

updates  to  disk 

segment_flush( ) . 

182 

convert  string  to 

upper  case 

G_toucase( ) 

114 

command  line 

usage  message 

G_paise_commancLusage( ) 

-111 

interact  with  the 

user 

V_call( ) 

189 

usei^s  home  directory 

G_home( ) 

117 

user's  name 

G_whoami( ) 

118 

get  mouse  location 

using  a  box 

R_get.location_with_box( ) 

157 

get  mouse  location 

using  a  line 

R_geLlocalion_with_line< ) 

156 

get  mouse  location 

using  pointer 

R^Glocation_with_pointer( ) 

156 

prompt  for  any 

valid  file  name 

G_ask_any( ) 

70 

prompt  for  any 

valid  group  nanoe 

Lask_group_any( ) 

139 

get 

value  from  segment  file 

3egment_get( ) 

181 

put 

value  to  segment  file 

segment,  putt ) 

182 

query  GRASS  emironment 

variable 

G__getEnv( ) 

67 

quety  GRASS  environment 

variable 

G.getenv( ) 

67 

set  GRASS  emironment 

variable 

G _ setenvt ) 

67 

set  GRASS  environment 

variable 

G_setenvt ) 

67 

end  level  one 

vector  access 

dig_fini( ) 

125 

initialize  level  one 

vector  access 

dig_initt ) 

125 

end  kwe)  two 

vector  access 

dig_P_fini( ) 

128 

initialize  level  two 

e'er  tor  access 

dig_r_irut< ) 

128 

read 

vector  category  file 

G_read_vector_cats(  •) 

105 

write 

vector  categoiy  file 

G_wiite_vector_caiB( ) 

105 

rewind 

vector  file 

dig_a^wind( ) 

125 

prompt  for  an  existing 

vector  file 

G_asl\_vector_in_mapsett ) 

101 

prompt  for  a  new 

vector  file 

G_aBievector_new( ) 

101 

prompt  for  an  existing 

vector  file 

G_a6k_vector_old( ) 

101 

find  a 

vector  file 

G_find_vector2( ) 

102 

find  a 

vector  file 

G_find_vectDr< ) 

102 

open  a  new- 

vector  file 

G_fopen_vector_new(  i 

104 

open  an  existing 

vector  file 

G_fopc‘n_vector_old( ) 

103 

read 

vector  header 

dig_reacLheacLbinaiy(  ) 

i;i4 

wnte 

vector  header 

dig_wnte_hejd_binaryt  ) 

134 

display 

vector  header  infomiiilion 

clig_pnnt_header( ) 

126 

temporary  close 

vector  map 

dig_l’_UTip_close< ) 

128 

rc-open  c  losed 

vector  map 

dig_l’.tmp_open( ) 

128 

pnntable 

version  of  control  thnrai  ter 

G_untui( ) 

1 14 

print 

warning  message  iiiul  continue 

G.wiuningt ) 

64 

suppress 

warnings? 

('•.suppress. warnings!  ) 

65 

make  color 

wi^'e 

G.malvt'.color.wac'et  ) 

97 

leinove  untK’cessaiy 

white  space- 

G.sijueezet  ) 

113 

remove  Icixiing/U-aming 

white  space 

(J.suipt  ) 

1 14 

assign/ieti-ieve  cunent  map 

window 

D.chc'clc.map.wirxlow  t  ) 

160 

■iu-s  inrormation  about  cunent 

window 

D.ck'ar.windowt ) 

161 

clip  ctxrrdi nates  to 

window 

D.clipl  ) 

166 

erase  current 

window 

D_er.tie_window(  ) 

161 

identily  current  graphics 

window 

D.get.cur.w  indt ) 

160 

create  new  graphics 

window 

D.ik'w  wirxlowt ) 

]6<) 

leiTxive  a 

window 

l)„remo\e_w  indow(  ) 

161 

^■t  cunent  graphics 

window 

D.wt.cur.wiixK  ) 

16(1 
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outlines  current 

window 

D_ahow_window( ) 

160 

give  current  time  to 

window 

D_timestamp< ) 

161 

read  the  default 

window 

G_get_default_wirxlow( ) 

78 

get  the  active 

window 

G_get_set_wiixlo\v( ) 

79 

read  the  database 

window 

G_get_window( ) 

77 

write  the  database 

window 

G_put_window( ) 

77 

set  the  active 

window 

G_set_window( ) 

79 

number  of  columns  in  active 

window 

G_window_cols( ) 

78 

number  of  rows  in  active 

window 

G_  window _nDws() 

78 

set  text  clipping 

window 

R_set_window( ) 

165 

retrieve  current 

window  coordinates 

D_get_9cteen_window( ) 

160 

add  commarxl  to 

window  display  list 

D_add_to_list( ) 

161 

clear 

wiixlow  displ^  lists 

D_clear_window( ) 

161 

resets  current 

window  position 

D_ieaet_screen_window( ) 

161 

read  a  cell  file 

(without  masking) 

G_get_nr»ap_row_nDmask( ) 

87 

tender  a  raster  row 

without  zeros 

D_overtay_cell_row( ) 

166 

write  a  cell  file  (random) 

G_puLmap_row_rarxlom( ) 

88 

write  a  cell  file  (sequential) 

G_put_map_row( ) 

88 

write  a  row 

rowio_puti ) 

176 

write  arc 

dig_Write_line( ) 

133 

write  cell  eatery  file 

G_write_cats( ) 

92 

write  cell  history  file 

G_wTite_histoiy( ) 

99 

write  cell  range 

G_write_range( ) 

100 

write  group  control  points 

Lput_controLpoints( ) 

144 

write  group  REF  file 

l_put_group_ief( ) 

140 

write  map  layer  color  table 

G_write_colors( ) 

95 

write  row  to  segment  file 

segmcnt_put.tt>w( ) 

181 

write  site  list  file 

G_put_site( ) 

108 

write  subgroup  REF  file 

Lput_subgroup_rrf( ) 

140 

write  target  information 

Lput_taiget( ) 

142 

write  text 

R^texW ) 

156 

write  the  cell  header 

G_put_cellhd( ) 

90 

write  the  database  witxlow 

G_fxit.window( ) 

77 

write  vector  category  file 

G_wTite_vector_cals( ) 

105 

write  vector  header 

dig_wiite_head_binary( ) 

134 

screen  to  array 

(x) 

D_cLto_a^col( ) 

164 

sc  teen  to  earth 

(X) 

D_d_to_u_col( ) 

164 

sc  nren  to  array 

(.V) 

D_d_to_a_row( ) 

164 

scieen  to  earth 

(y) 

D_tLto_u_row( ) 

164 

ask  a 

yes/no  question 

G_yes( ) 

118 

zero  a  cell  bufter 

G_zero_celLbur( ) 

86 

under  a  r.ister  row  without 

zeros 

l)_overiav_cell_tDw( ) 

165 

queiy  cartographic 

zone 

O_zone(  ) 

80 
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$ 

$GISBASE  51 
$G1SDBASE  16 
$G]SRC  51 
$GISlLOCK  51 
SLOCAHONJ^AME  16 
$MAPSET  16 


.gidock  170 
.grasstc  15,  52 
gisdbaee  52 
location  52 
mapeet  52 
.h  files; 

see:  include  files 

A 

access  penrissions: 

GRASS  20 
UNIX  20 
Approach  1 

B 

Background  1 
band  files  41 
Bourne  Shell; 
shell  sciipts  229 

c 

category  file: 

see:  cell  files,  vector  files 
category  nurrber. 
cell  23 
vector  31 

CELL  79,  80,  K6,  K7,  K«,  m, 
1H.5,  237 
ceil  files  23 
see  also:  GIS  Library 
allocate  CELL  buffer  85 
and  the  database  24 
category  file  28,  91 
category  number  23 
cell  file  format  24 
cell  header  26,  89 
closing  89 
color  file  28.  94 


Index 


finding  82 
history  file  29, 96 
opening  (new)  84 
opening  (read)  83 
progtanming  interface  24,80 
pronpting  for  81 
rapge  file  29,  99 
reading  86 
reclasB  format  27 
resolution  27 
writing  87 
cell  header. 

see:  cell  files 
color  table: 

see:  cell  files 
colors; 

see;  cell  files 

see:  Diqrl^  (jte^cs  Iibr«y 
see:  Ra^  (jr^hics  Library 
colots.h  160 
compiling: 

(jmake  56,  122,  135,  144,  157,  167,  170,  177,  185, 
191 

curses: 

Gn»ke  SJ 

Vask  library  187,  191, 193 


D 

database; 

access  permisaons  20 
programming  interface  15, 68 
search  path  20 
title  19,66 
database  structure  15 
$GISDBASE  16 
location  16 

$L(XATION_NAME  16 
SMAPSET  16 
mapeet  16 

94,  95,  96,  97,  96,  100,  date: 

G_date( )  117 
DEFAULT_WIND  19 
diagnostics: 

see:  error  messages 
Dig  library  12,  123 
arc  types  124 
include  files  123 
INDEX  of  routines  243 
INDEX,  permuted  257 
level  one  access  124 
level  two  access  127 
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levels  of  access  124 
LOADING  the  library  135 
writing  vector  files  133 
digit  files: 

see:  vector  files 
dig_: 

index  of  dig_  routines  (Dig  library)  243 
dig_definesii  124, 126 
dig_structsii  124 

Display  Gr^Aics  library  12, 57,  159 
colors  ICT 

coordinate  tran^orrnation  162 
INDEX  of  routines  247 
INDEX,  permuted  257 
LOADING  the  library  167 
popcp  menus  166 
raster  graphics  164 
window  clipping  165 
wirxlow  contents  161 
windows  159 
drivers: 

writing  a  digitizer  driver  196 
writing  a  graphics  driver  207 
writing  a  paint  driver  215 
D_: 

irxiex  of  D_  routines  (Di^lay  Graphics 
Library)  247 

E 

elements  17,  18 
environment  15,  61,  66 

G _ getenvt )  67 

G_getenv(  )  67 
G_gisbase( )  66 
G_gisdbase(  )  67 
SGISBASE  51 
gisdbase  52 
$GLS_LOCK  51 
$GISRC  51 
G_localion(  i  66 
G^mapsetl  I  66 
GRASS  52 
•grassic  52 
G  _^sf‘tBnv(  I  67 
(^i  setpnv(  I  67 
l(XTltion  52 
mapset  52 
LINK  51 

enur  messages  64 
GIS  ERROR  lOG  64 


F 

fotk(  )  84 
GLforkO  116 


G 

Cask: 

and  ^11  scripts  230 
getsO: 

G^ts( )  117 
Gfindfile: 

and  ^11  scripts  2:11 
GIS  library  11, 56,  63 
allocate  CEILL  buffer  85 
andUNK  115 
cell  category  file  91 
cell  color  t^le  94 
cell  file  support  89 
cell  files  W 
cell  header  89 
ceil  history  file  98 
cell  rarige  99 
closing  cell  files  89 
comn»nd  line  parang  109 
data  structures  118 
database  access  68 
database  information  66 
database  management  75 
erivironiTierit  iiifortnation  66 
error  messages  64 
finding  ceil  files  82 
firxling  database  files  70 
finding  vector  files  102 
fork( )  115 
gets( )  117 

INDEX  of  routines  239 
INDEX,  permuted  257 
initialization  64 
legal  file  names  72 
LOADING  the  library  122 
memory  allocation  75 
open  cell  file  (new)  84 
open  cell  file  (read)  83 
opening  a  vector  file  (read)  108 
opening  database  files  (read)  72 
opening  database  files  (update)  73 
opening  database  files  (writs)  74 
opening  ate  files  107 
opening  vector  files  (new)  104 
projection  79 
prorrptir^  for  cell  files  81 
prompting  for  database  files  68 
proirpting  for  ate  files  106 
prompting  for  vector  files  101 
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reading  and  writing  ate  files  107 
reading  cdl  files  88 
sites  106 

string  routines  113 
struct  Cat^ries  119 
struct  CelLhead  119 
struct  Colors  120 
struct  Hstniy  121 
struct  Range  122 
systemO  116 
tempfiles  106 
vector  categoiy  file  104 
vector  files  100 
window  76 
writing  cell  files  87 
gis.h  56,  63,  76,  80,  118,  137,  237 
gisdbase  52 
•grasstc  52 

GIS_ERROiLLOG  64 
Gmake  11,66,202,216,225 
variables  56,233 

Gmakefile  11,66,202,207,216,225,226 
and  Dig  bltrary  135 
and  Grajiiics  libiaiy  167 

andOSIifataiy  122 
and  Imageiy  lihaiy  144 
and  Lock  libraiy  170 
and  Raster  Gn^cs  library  lf?7 
and  Rowio  library  177 
and  S^nient  lilxBiy  186 
and  Vask  library  191 
construction  of  58 
graphics: 

see:  Di^’sy  Gr^hics  libraiy 
see:  Ra^r  Gre^hics  library 
GRASS: 

Informafacin  Center  2,  3,  4 
Inter-Agt  cy  Steering  Comritee  3 
User  Grot?)  Meeting  3 
GRASSab  lings  3 
GRASSNET  3 
grid  cell: 

see:  cell  f.les 
group  41, ’  7, 138 
see  also:  imagery  library 
finding  lij9 
POINTS  fte  44 
POINTS  file  routines  143 
programming  interface  46 
prompting  for  138 
REF  file  43 
REF  file  routines  139 
structure  of  a  group  43 
subgroup  44 
TARGET  file  44 


TARGST  file  rotiines  142 
Guidelines  6 
GL: 

index  of  GL  routinee  (QS  library)  239 

H 

hisbty  file: 

see:  cell  files 
home  diiBctoiy: 

GJrotTBO  117 

I 

imagery: 
band  files  41 
image  classification  42 
image  rectification  42 
image  r^stiation  42 
programs  46 

xy  projection  26,42,48,80 
Imagery  library  137 
data  structures  144 
fiixling  groi^  139 
grorp  138 

gtotp  POINTS  files  -143 
groipREFfile  139 
group  TARGET  file  142 
INDEX  of  routines  245 
INDEX,  permuted  267 
LOADING  the  liixary  144 
pronpting  for  a  gtoip  138 
struct  Corirol_R)ints  146 
struct  REF  144 
imagery  ii  137, 139, 143, 144 
import 

vector  files  38 
include  files: 
colorsJi  160 
dig_clefines.h  124, 126 
dig_structs.h  124 
^S.h  56,  63,  76,  80, 118,  137,  237 
imagery.h  137, 139, 143, 144 
rowio  .h  174 
segmenth  180 
itxlex; 

Dig  library  243 
Di^ay  Graphics  library  247 
GIS  Library  239 
Imagery  library  246 
permutol  257 

Raster  Graphics  library  2AS 
Rowio  library  251 
Segment  library  263 
Vask  library  265 


-278- 


-278- 


inh‘mq)t  chnmctpr 
( )  117 

L: 

index  of  L  routines  (Imageiy  libraiy)  246 


mflthlib: 

Oneke  57 
MYNAME  19 
G.n^roameO  66 


L 


O 


libraiy; 

see:  Dig  libraiy 
see:  Di^sy  Graphics  Libraiy 
see:  GIS  library 
see:  Imageiy  library 
see:  Lock  Libraiy 
see:  Raster  Graphics  libraiy 
see:  Rowio  libraiy 
see:  Segment  Library 
see:  Vask  Library 
how  to  build  60 
permuted  index  257 
location  52 

G_location(  )  66 
.grassrc  52 
Lock  Libraiy  169 
INDEX,  permuted  257 
LOADING  the  libraiy  170 
login  name: 

G_wlioami( )  118 
longitude/latitude: 
see:  projection 

M 

map: 

see:  cell  files,  vector  files 
map  layer 

see:  cell  files,  vector  files 
mapset  16,  24,  .S2, 52 
access  permissions  20 
cell  files  24 

cunent  majxset  16,  2<t,  47,  4S,  66,  6S,  70,  7i,  7.4, 
71.  75,  77,  «l,  62,  K‘l,  M,  00,  02,  05,  99,  100,  101, 
102,  10.).  104,  105,  106,  107,  l.'tS,  149 

eleiumts  i7.  18 
files  17 
G_mapset(  i  66 
.grasstc  .52 
■SMAPSEl'  16 

ma,sk  4h 

PERMANt-^ST  17,  19 
seaivli  path  17,  20, 69,  7i.  62.  64,  102 
structure  of  a  mapset  17 
sulvliii’ctoiies  17 
vector  files  .12 
wiikIow  17,  47 
mask  1.6 


Objective  1 

P 

paispg: 

G_parse_commands( )  109,  111 
PERMANENT  17,  19 
access  permissions  21 
default  window  19 
DEFAL’LT_WIND  19 
MYNAME  19,66 
permuted  index  257 
point  data 
see:  site  files 
Ftogrammer 
drivers  12 
GRASS  10 
system  designer  1,3 
Rngranming: 
compiling  55 
interface  to  cell  files  24,  80 
interface  to  groi^  46 
interface  to  ale  files  40,  106 
interface  to  the  database  15,  68 
interface  to  vector  files  .42,  100,  123 
programming: 

standards  6 
projection  26,46 
GIS  Libraiy  79 
imageiy  (xy)  26, 42,  48,  80 
longitude/ladtude  5 
State  Hane  26,  48,  80 
UTM  5,  26,  27.  42,  44,  48.  80,  164 
zone  26,  46 


R 

range  file: 

see:  cell  files 
raster  files: 
see:  cell  files 

Raster  Graphics  Library  12,  .56,  147 
basic  graphics  150 
colors  148 

connecting  to  the  driver  148 
INDEX  of  routines  249 
INDEX,  permuted  257 
LOADING  the  library  157 
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tnouse  156 
poly  calls  162 
ras^  calls  153 
text  164 
teclass  files: 

see:  cell  files 
resolution: 
cell  file  27 
window  48 
Rowio  library  173 
INDEX  of  routines  251 
INDEX,  permuted  267 
LOADING  the  library  177 
rowio  .h  174 
rowio_: 

index  of  rowio_  routines  i  Rowio  libmy)  261 

R_: 

index  of  R_  routines  (Rasto'  GrEqshics 
library)  249 

S 

Scope  2 

search  path  17,  20, 69. 7i,  82, 83, 102 
Segment  library  ii ,  56, 179 
INDEX  of  routines  253 
INDEX,  permuted  267 
LOADING  the  library  185 
segmenth  180 
segmenL; 

index  of  segment,  routines  (S^nwit 
library)  253 
shell  scripts  is,  229 
Bourne  Shell  229 
Cask  230 
Gfindfile  23i 
ate  files  39 
file  format  39 
opening  107 

prograrrmng  interface  4o,  106 
pronptingfor  106 
reading  arxi  writing  107 
Standards; 
documentation  7 
programming  6 
State  Rane: 

see;  projection 
string  routines; 

GIS  library  1 13 
structures; 

P_AREA  12!).  1.32 

struct  Categories  91, 92, 9:1,  94,  1O6,  119 
struct  CelLhead  76,  77,  78,  79, 90,  119, 160, 162 
struct  Colors  94,  95,  96,  97,  98,  120, 167 
struct Command_keys  109,  110,  in,  113 


struct  CorteUbintB  143, 144, 146 
struct  digjbead  134 
struct  Hstnry  96,99,121 
struct  line_pnl8  130, 131, 133, 135 
struct  Mspjrtfo  128,  129, 130, 131, 132,  133 
struct  Raige  99, 100, 122 
struct  Ref  139, 140,  i4i,  142, 144 
sidbgroiq)  44 
gistemO: 

G-systemO  116 

T 

target 
see;  group 

Technology  Tranrfer  2 
tBnncf9),tBrmIib; 

Gm^  67 

Va^  library  187,  191 

u 

UNK; 

access  permissions  20 
environment  5i 
forkO  84,  115 
getsO  117 
systemO  116 
User 
general  9 
UIM: 

see:  projection 

V 

Vask  library  56,  187 
INDEX  of  routines  256 
INDEX,  permited  257 
LOADING  the  library  191 
vector  files  31 
see  also;  Dig  library 
ascii  format  32 
attribute  file  35 
category  file  36,  104 
category  number  31 
digitizer  registration  37 
firxling  102 
inport  38 

irxiex  and  pointer  file  37 
opening  (new)  104 
opening  (read)  103 
programming  interface  32,  100,  123 
pronptiiig  for  101 
reading  and  writing  104 
topology  rules  37 


